/ home / the Javascript SIP library / Documentation / 3.7.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 a RTCPeerConnection instance, accessible via the connection attribute.

Instance Attributes

connection

The underlying RTCPeerConnection instance associated to this session. Use it to set events related to WebRTC (such as onaddstream, onaddtrack, etc).

Note that, for outgoing calls, the RTCPeerConnection is set after calling ua.call(). However, for incoming calls the RTCPeerConnection is set after calling session.answer().

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

An object for the application to store custom information associated to this session.

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.
transportType
Optional String ‘INFO’ or ‘RFC2833’. Default value is ‘INFO’

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);

Example 3

var options = {
  'transportType': 'RFC2833'
};

call.sendDTMF(1, options);

sendInfo(contentType, body=null, options=null)

Send a SIP INFO message.

contentType
String representing the SIP INFO message Content-Type header field value.
body
Optional String representing the SIP INFO message body.
options
Optional Object with extra parameters. See below.

Fields in options Object

extraHeaders
Optional Array of Strings with extra SIP headers for each INFO request.

Throws

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
}

refer(target, options=null)

Sends an in-dialog REFER method with the given target as the Refer-To resource.

A REFER method implicitly generates a subscription to the state of the refer. The NOTIFY requests received from the peer are processed and presented in form of events by JsSIP.RTCSession.ReferSubscriber.

Parameters

target
Refer-To resource. String representing a destination username or a complete SIP URI, or a JsSIP.URI instance.
options
Optional Object with extra parameters (see below).

Fields in options Object

extraHeaders
Optional Array of Strings with extra SIP headers for the REFER request. If a “Referred-By” entry is present, it will be used on the outgoing REFER request.
eventHandlers
Optional Object of event handlers to be registered for the JsSIP.RTCSession.ReferSubscriber.
replaces
Optional JsSIP.RTCSession instance which dialog is meant to be replaced at the refer target. This is a live session between this user agent and the one pointed by the Refer-To resource.

Throws

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

Fired once the underlying RTCPeerConnection is created. The application has a chance here to alter the peerconnection by, for example, adding a RTCDataChannel on it, or to set the corresponding event listenters.

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.

sending

Fired just before the initial INVITE is sent (just for outgoing calls). It provides a chance for the app to mangle the SIP INVITE or its SDP.

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.

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.

newInfo

Fired for an incoming or outgoing SIP INFO message.

Event data fields for an incoming SIP INFO message.

originator
‘remote’ String. The new SIP INFO message is generated by the remote peer.
info
JsSIP.RTCSession.Info instance.
request
JsSIP.IncomingRequest instance of the received INFO request.

Event data fields for an outgoing SIP INFO message.

originator
‘local’ String. The new SIP INFO message. is generated by the local user.
info
JsSIP.RTCSession.Info 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.

muted

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.

unmuted

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.
reject()
Denial Method to be executed if the re-INVITE is rejected. 403 response code is used by default.

Event data.reject() 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.

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.
reject()
Denial Method to be executed if the re-INVITE is rejected. 403 response code is used by default.

Event data.reject() 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.

refer

Fired when an in-dialog REFER is received.

If the refer aproval is granted, a new outgoing JsSIP.RTCSession is generated to the target indicated in the Refer-To header field.

The NOTIFY mechanism is used to inform the agent sending the REFER of the status of the reference as defined in RFC 3515.

NOTE: The Refer-To resource is accessible in the incoming JsSIP.IncomingRequest refer_to JsSIP.URI attribute.

Event data fields

request
JsSIP.IncomingRequest instance of the received REFER request.
accept()
Consent approval Method to be executed if the REFER is accepted. This generates an outgoing JsSIP.RTCSession to the resource identified by the Refer-To URI.
reject()
Consent denial Method to be executed if the REFER is rejected.

Event data.accept() parameters

newRTCSession(session)
Optional callback Function to be executed on behalf of JsSIP.UA newRTCSession event for the new outgoing RTCSession. If this function is not defined, the former event will be emitted.
options
Optional Object providing the options for the outgoing JsSIP.RTCSession. The semantic of this parameter corresponds to the optional parameter for JsSIP.UA call method.

Event data.reject() parameters

This method does not require any parameter.

replaces

Fired when an out of dialog INVITE is received pointing to this RTCSession through the Replaces header field.

Granting approval makes the current JsSIP.RTCSession terminate when the new one is established.

Event data fields

request
JsSIP.IncomingRequest instance of the received INVITE request.
accept()
Consent approval Method to be executed if the INVITE is accepted. An incoming JsSIP.RTCSession will be generated.
reject()
Consent denial Method to be executed if the INVITE is rejected.

Event data.accept() parameters

newRTCSession(session)
Optional callback Function to be executed on behalf of JsSIP.UA newRTCSession event for the new incoming RTCSession. If this function is not defined, the former event will be emitted.

Event data.reject() parameters

This method does not require any parameter.

sdp

Fired before passing a remote SDP to the RTC engine, and before sending out a local SDP.
This event provides the mechanism to modify incoming and outgoing SDP.

Event data fields

originator
String indicating whether the SDP is locally generated or was remotely received. Possible values are local or remote respectively.
type
String indicating whether the SDP is an offer or an answer.
sdp
String representing the SDP. Modifications must be done directly on this parameter.

icecandidate

Fired for each gathered local ICE candidate while requesting RTCPeerConnection for the local description.
This event provides the mechanism to stop waiting for more ICE candidates to be gathered so that the local description can be sent out (as an SDP offer or answer) before the whole ICE gathering process finishes.

NOTE: See RTCIceCandidate specification for detailed info on the event data type candidate

Event data fields

candidate
RTCIceCandidate instance as described in the W3C specification.
ready
Function to be executed by the event callback if candidate is the last one to be gathered prior to retrieve the local description.

getusermediafailed

Fired when an internal call to getUserMedia() fails. It provides the DOMException as argument.

peerconnection:createofferfailed

Fired when an internal call to createOffer() fails. It provides the DOMException as argument.

peerconnection:createanswerfailed

Fired when an internal call to createAnswer() fails. It provides the DOMException as argument.

peerconnection:setlocaldescriptionfailed

Fired when an internal call to setLocalDescription() fails. It provides the DOMException as argument.

peerconnection:setremotedescriptionfailed

Fired when an internal call to setRemoteDescription() fails. It provides the DOMException as argument.

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