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

Instance Attributes

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

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 MESSAGE request.
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 both audio and video set to true.
RTCAnswerConstraints
Object representing constraints for RTCPeerconnection createAnswer.
mediaStream
MediaStream to transmit to the other end.

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

getLocalStreams()

Returns a sequence of MediaStream objects representing the streams that are currently sent in this RTCSession.

getRemoteStreams()

Returns a sequence of MediaStream objects representing the streams that are currently received in this RTCSession.

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

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

Throws

unhold()

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

Throws

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.

Every event handler is executed with a JsSIP.Event instance as the only argument.

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.

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.

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.

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