/ home / the Javascript SIP library / Documentation / 1.0.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
}

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.
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

resetLocalMedia()

Reset the local MediaStream by enabling both its audio and video tracks (unless the remote peer is on hold).

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. Also fired for incoming calls without SDP offer.

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

iceconnectionstatechange

Fired when ICE connection state changes for the current RTCPeerConnection.

Event data fields

state
The RTCPeerConnection ICE connection state.

Possible ICE connection states are defined here

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.

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.

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.
sdp
String representing the SDP. Modifications must be done directly on this parameter.

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