/ home / the Javascript SIP library / Documentation / 0.6.x / API / JsSIP.RTCSession

Class JsSIP.RTCSession

The class JsSIP.RTCSession represents a WebRTC media (audio/video) session. It can be initiated by the local user or by a remote peer.

Internally it holds an instance of rtcninja.RTCPeerConnection (accessible via the connection attribute).

Instance Attributes

connection

The rtcninja.RTCPeerConnection instance.

direction

String indicating who started the session. Possible values are ‘incoming’ when the session is started by the remote peer or ‘outgoing’ when the session is started by the local user.

local_identity

JsSIP.NameAddrHeader instance indicating the local identity. It corresponds with the INVITE From header value when the direction is ‘outgoing’, and with the To header value when the direction is ‘incoming’

remote_identity

JsSIP.NameAddrHeader instance indicating the remote identity. It corresponds with the INVITE To header value when the direction is ‘outgoing’, and with the From header value when the direction is ‘incoming’

start_time

Date object indicating the time when the session started. Takes its value at the moment when accepted event was fired.

end_time

Date object indicating the time when the session ended. Takes its value at the moment when ended event was fired.

data

Custom session empty Object for application usage. The developer can add here custom attribute/value pairs.

Instance Methods

isInProgress()

Returns true if the session is in progress state (not established and not ended).

isEstablished()

Returns true if the session is established.

isEnded()

Returns true if the session is ended.

isReadyToReOffer()

Returns true if the session is ready for a SDP renegotiation (hold(), unhold() or renegotiate() methods).

answer(options)

Answer the incoming session. This method is available for incoming sessions only.

Parameters

options
Optional Object with extra parameters (see below).

Fields in options Object

extraHeaders
Array of Strings with extra SIP headers for the 200 OK response.
mediaConstraints
Object with two valid fields (audio and video) indicating whether the session is intended to use audio and/or video and the constraints to be used. Default value is set according to the received SDP offer.
mediaStream
MediaStream to transmit to the other end.
pcConfig
Object representing the RTCPeerConnection RTCConfiguration.
rtcConstraints
Object representing RTCPeerConnection constraints.
rtcAnswerConstraints
Object representing constraints for RTCPeerConnection createAnswer().
rtcOfferConstraints
Object representing constraints for RTCPeerConnection createOffer() (to be used for future incoming reINVITE without SDP offer).
sessionTimersExpires
Number (in seconds) for the default Session Timers interval (default value is 90, do not set a lower value).

Throws

terminate(options)

Terminate the current session regardless its direction or state.

Depending on the state of the session, this function may send a CANCEL request, a non-2xx final response, a BYE request, or even no request.

For incoming sessions, if the user has not answered the incoming INVITE, this function sends the non-2xx final response with the optionally specified status code and reason phrase. 480 Unavailvable is responded by default.

For outgoing sessions, if the original INVITE has not been already sent, it will never be sent. If the original INVITE has not been answered with a final response, the behavior depends on whether provisional response has been received. If provisional response has been received, a CANCEL request will be sent. If no provisional response has been received, the function will not send a CANCEL as per RFC 3261. If then a provisional response is received, the CANCEL request will be automatically sent.

For both incoming and outgoing, if the INVITE session has been answered with final response, a BYE request will be sent.

Parameters

options
Optional Object with extra parameters (see below).

Fields in options Object

extraHeaders
Array of Strings with extra SIP headers for the MESSAGE request.
status_code
Number between 300 and 699 representing the SIP response code.
reason_phrase
String representing the SIP reason phrase.
body
String representing the SIP message body (in case this parameter is set, a corresponding Content-Type header field must be set in extraHeader field).

NOTE: When generating a CANCEL, status_code can take values from 200 to 699. The status_code and reason_phrase will form a Reason header field as specified in RFC3326. A CANCEL will not take the extraHeaders parameter nor the body paramter.

Throws

sendDTMF(tone, options=null)

Send one or multiple DTMF tones making use of SIP INFO method.

tone
String or Number composed by one or multiple valid DTMF symbols.
options
Optional Object with extra parameters. See below.

Fields in options Object

duration
Positive decimal Number indicating the duration of the tone expressed in milliseconds. Default value is 100.
interToneGap
Positive decimal Number indicating the interval between two tones expressed in milliseconds. Default value is 500.
extraHeaders
Optional Array of Strings with extra SIP headers for each INFO request.
eventHandlers
Optional Object of event handlers to be registered to each JsSIP.RTCSession.DTMF event. Define an event handler for each event you want to be notified about.

Throws

Example 1

call.sendDTMF(1);
call.sendDTMF(4);

Example 2

var tones = '1234#';

var extraHeaders = [ 'X-Foo: foo', 'X-Bar: bar' ];

var options = {
  'duration': 160,
  'interToneGap': 1200,
  'extraHeaders': extraHeaders
};

call.sendDTMF(tones, options);

hold(options=null, done=null)

Puts the call on hold by sending a Re-INVITE or UPDATE SIP request.

Returns false if the renegotiation is not possible at this time.

options
Optional Object with extra parameters. See below.
done
Optional Function called once the renegotiation has succeeded.

Fields in options Object

useUpdate
Boolean Send UPDATE instead of re-INVITE
extraHeaders
Array of Strings with extra SIP headers for the request.

unhold(options=null, done=null)

Resumes the call from hold by sending a Re-INVITE or UPDATE SIP request.

Returns false if the renegotiation is not possible at this time.

options
Optional Object with extra parameters. See below.
done
Optional Function called once the renegotiation has succeeded.

Fields in options Object

useUpdate
Boolean Send UPDATE instead of re-INVITE
extraHeaders
Array of Strings with extra SIP headers for the request.

renegotiate(options=null, done=null)

Forces a SDP renegotiation. Useful after modifying the local stream attached to the underlying RTCPeerConnection (via the connection attribute).

Returns false if the renegotiation is not possible at this time.

options
Optional Object with extra parameters. See below.
done
Optional Function called once the renegotiation has succeeded.

Fields in options Object

useUpdate
Boolean Send UPDATE instead of re-INVITE
extraHeaders
Array of Strings with extra SIP headers for the request.
rtcOfferConstraints
Object representing constraints for RTCPeerConnection createOffer().

isOnHold()

Returns an Object with the properties “local” and “remote” and a Boolean value asociated with each one. It represents whether the “local” and/or “remote” peer are on hold.

Example

rtcsession.isOnHold();

{
  'local': true,    // User has put the other peer on hold
  'remote': false   // Peer hasn't put user on hold
}

mute(options=null)

Mutes the local audio and/or video.

audio
Boolean Determines whether local audio must be muted
video
Boolean Determines whether local video must be muted

unmute(options=null)

Unmutes the local audio and/or video.

audio
Boolean Determines whether local audio must be unmuted
video
Boolean Determines whether local video must be unmuted

isMuted()

Returns an Object with the properties “audio” and “video” and a Boolean value asociated with each one. It represents whether the local “audio” and/or “video” are on muted.

Example

rtcsession.isMuted();

{
  'audio': true,   // Local audio is muted
  'video': false   // Local audio is not muted
}

Events

JsSIP.RTCSession class defines a series of events. Each of them allow callback functions registration in order to let the user execute a function for each given stimulus.

peerconnection

Just fired for outgoing calls once the internal RTCPeerConnection is created but before the SDP offer is generated.

The application has a chance here to alter the peerconnection by, for example, adding a RTCDataChannel on it.

Event data fields in outgoing sessions

peerconnection
The RTCPeerConnection instance.

Example

var datachannel;

session.on('peerconnection', function(data) {
  datachannel = data.peerconnection.createDataChannel('chat');
});

connecting

Fired after the local media stream is added into RTCSession and before the ICE gathering starts for initial INVITE request or “200 OK” response transmission.

Event data fields in incoming sessions

request
JsSIP.IncomingRequest instance representing the incoming INVITE SIP message.

Event data fields in outgoing sessions

request
JsSIP.OutgoingRequest instance representing the outgoing INVITE SIP message.

progress

Fired when receiving or generating a 1XX SIP class response (>100) to the INVITE request.

The event is fired before the SDP processing, if present, giving the chance to fine tune it if required or even drop it by removing the body of the response parameter in the data object.

Event data fields in incoming sessions

originator
‘local’ String.

Event data fields in outgoing sessions

originator
‘remote’ String.
response
JsSIP.IncomingResponse instance of the received SIP 1XX response.

accepted

Fired when the call is accepted (2XX received/sent).

Event data fields in incoming sessions

originator
‘local’ String.

Event data fields in outgoing sessions

originator
‘remote’ String.
response
JsSIP.IncomingResponse instance of the received SIP 2XX response.

confirmed

Fired when the call is confirmed (ACK received/sent).

Event data fields in incoming sessions

originator
‘local’ String.

Event data fields in outgoing sessions

originator
‘remote’ String.
response
JsSIP.IncomingResponse instance of the received SIP 2XX response.

ended

Fired when an established call ends.

Event data fields

originator
‘local’/‘remote’/‘system’ String. Where does the call termination come from.
message
JsSIP.IncomingRequest or JsSIP.IncomingResponse instance generating the call termination when originator value is ‘remote’, null otherwise.
cause
One value of Failure and End Causes.

failed

Fired when the session was unable to establish.

Event data fields

originator
‘local’/‘remote’/‘system’ String. Where does the call failure come from.
message
JsSIP.IncomingRequest or JsSIP.IncomingResponse instance generating the call failure when originator value is ‘remote’, null otherwise.
cause
One value of Failure and End Causes.

addstream

Fired when a remote stream is added.

Event data fields

stream
The remote MediaStream

removestream

Fired when a remote stream is removed.

Event data fields

stream
The remote MediaStream

newDTMF

Fired for an incoming or outgoing DTMF.

Event data fields for an incoming DTMF

originator
‘remote’ String. The new DTMF is generated by the remote peer.
dtmf
JsSIP.RTCSession.DTMF instance.
request
JsSIP.IncomingRequest instance of the received INFO request.

Event data fields for an outgoing DTMF

originator
‘local’ String. The new DTMF is generated by the local user.
dtmf
JsSIP.RTCSession.DTMF instance.
request
JsSIP.OutgoingRequest instance of the outgoing INFO request.

hold

Fired when the user or the peer puts the other side on hold.

Event data fields

originator
‘remote’ String if the other peer has put the user on hold. ‘local’ String if the user has put the other peer on hold.

unhold

Fired when the user or the peer resumes the other end from hold.

Event data fields

originator
‘remote’ String if the other peer has resumed the user from hold. ‘local’ String if the user has resumend the other peer from hold.

mute

Fired when the local media is muted.

Event data fields

audio
Boolean Determines whether the local audio is muted.
video
Boolean Determines whether the local video is muted.

unmute

Fired when the local media is unmuted.

Event data fields

audio
Boolean Determines whether the local audio is muted.
video
Boolean Determines whether the local video is muted.

reinvite

Fired when an in-dialog reINVITE is received.

Event data fields

request
JsSIP.IncomingRequest instance of the received reINVITE request.
callback
Initially undefined. If the user sets a function here it is executed once the reINVITE is processed.

update

Fired when an in-dialog UPDATE is received.

Event data fields

request
JsSIP.IncomingRequest instance of the received UPDATE request.
callback
Initially undefined. If the user sets a function here it is executed once the UPDATE is processed.

/ home / the Javascript SIP library / Documentation / 0.6.x / API / JsSIP.RTCSession