API

SIP.Session

The class SIP.Session represents a WebRTC media (audio/video) session. It can be initiated by the local user or by a remote peer. Sessions are created via SIP INVITE messages. Sessions also implement one of SIP.ClientContext or SIP.ServerContext, depending on if they are the result of outbound (client) or inbound (server) INVITE requests.

Construction

The Session constructor is intended for internal use only. Instead, outbound Sessions are created through the SIP.UA.invite method. Inbound Sessions are obtained via the SIP.UA invite event callback.

Examples

// Create a new outbound (User Agent Client) Session
var session = myUA.invite('alice@example.com');
// Accept an inbound (User Agent Server) Session
myUA.on('invite', function (session) {
  session.accept();
});

Instance Attributes

startTime

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

endTime

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

ua

SIP.UA - Inherited from SIP.ClientContext or SIP.ServerContext.

method

String - The value of method is always "INVITE". Inherited from SIP.ClientContext or SIP.ServerContext.

request

SIP.IncomingRequest or SIP.OutgoingRequest - Inherited from SIP.ClientContext or SIP.ServerContext.

localIdentity

SIP.NameAddrHeader - Inherited from SIP.ClientContext or SIP.ServerContext.

remoteIdentity

SIP.NameAddrHeader - Inherited from SIP.ClientContext or SIP.ServerContext.

data

Object - Empty object for application to define custom data. Inherited from SIP.ClientContext or SIP.ServerContext.

Instance Methods

dtmf(tone[, options])

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

Parameters

Name Type Description
tone String or Number One or multiple valid DTMF symbols. Converts Number to String using toString().
options Object Optional Object with extra parameters (see below).
options.extraHeaders Array Optional Array of Strings with extra SIP headers for each INFO request.
options.duration Number Positive decimal Number indicating the duration of the tone expressed in milliseconds. Default value is 100.
options.interToneGap Number Positive decimal Number indicating the interval between two tones expressed in milliseconds. Default value is 500.

Throws

TypeError INVALID_STATE_ERROR

Returns

Type Description
SIP.Session This Session

Example 1

call.dtmf(1);
call.dtmf(4);

Example 2

var tones = '1234#';

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

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

call.dtmf(tones, options);

bye([options])

Sends a BYE request on a confirmed session.

Parameters

Name Type Description
options Object Optional Object with extra parameters (see below).
options.status_code Number The SIP response code that will be used in the upcoming response instead of the default.
options.reason_phrase String The SIP reason phrase.
options.body String represents the SIP message body (in case this parameter is set, a corresponding Content-Type header field must be set in extraHeaders field).
options.extraHeaders Array of Strings Extra SIP headers for the request.

Throws

TypeError INVALID_STATE_ERROR

getLocalStreams()

Returns an array of MediaStream objects representing the streams that are currently sent in this Session.

Returns

Type Description
Array of MediaStream The local media stream

getRemoteStreams()

Returns an array of MediaStream objects representing the streams that are currently received in this session.

Type Description
Array of MediaStream The remote media stream

refer(target[, options])

Send a REFER request. A REFER occurs when persons A and B have an active call session, and A wants to transfer B to speak with C. This is called a transfer, and these transfers can be attended or blind. An attended transfer occurs when A creates a session with C before connecting B to speak with C. A blind transfer occurs when A causes B to create a session with C, so A and C have no contact. SIP.js only supports blind transfers.

Parameters

Name Type Description
target String The target address to be referred to.
options Object Optional Object with extra parameters (see below).
options.extraHeaders Array of Strings Extra SIP headers for the request.

Returns

Type Description
SIP.Session This session

Throws

TypeError INVALID_STATE_ERROR

Instance Methods (Outbound/Client)

cancel([options])

Overrides SIP.ClientContext.cancel

Instance Methods (Inbound/Server)

progress([options])

Overrides SIP.ServerContext.progress. Additional parameters specific to INVITE requests can be specified.

As per RFC 3262, non-100 provisional responses may be transmitted reliably. Support for this is determined by the initial invite request (see the rel100 parameter on ua.invite()). If the INVITE prohibits reliable provisional responses, all responses sent with progress will be transmitted unreliably. Likewise, if the INVITE requires 100rel, all non-100 responses will be sent reliably. If 100rel is supported, reliable transmission is determined by the options.rel100 parameter. Note that reliable provisional responses typically contain the SDP answer and so an options.media parameter is also provided.

Parameters

Name Type Description
options.rel100 Boolean If the INVITE request supports 100rel, progress responses will be transmitted reliably based on this option. If the INVITE request requires or does not support 100rel, this option is ignored.
options.media Object Media constraints to use in a reliable provisional response. After the response is PRACKed, early media will begin. If the session is later accepted, these media constraints will be used.
ServerContext Parameters   See SIP.ServerContext.progress.

accept([options])

Overrides SIP.ServerContext.accept. Additional parameters specific to INVITE requests can be specified.

Parameters

Name Type Description
options.media Object Media constraints to use for the Session. For example, { audio: true, video: true }.
options.mediaConstraints Object Deprecated - Same as options.media
ServerContext Parameters   See SIP.ServerContext.accept.

reject([options])

Overrides SIP.ServerContext.reject

reply([options])

Overrides SIP.ServerContext.reply

Events

The SIP.Session class defines a series of events. Each of them allows a callback function to be defined in order to let the user execute a handler for each given stimulus.

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

progress

Fired each time a provisional (100-199) response is received.

on('progress', function (response) {})

Name Type Description
response SIP.IncomingMessage The received response

accepted

Fired each time a successful final (200-299) response is received.

on('accepted', function (data) {})

Outbound sessions emit accepted with the following parameters:

Name Type Description
data Object A wrapper object containing the event data
data.code Number The status code of the received response, between 200 and 299.
data.response SIP.IncomingMessage The received response

Inbound sessions do not currently provide any parameters when emitting the accepted event. Track this bug on GitHub.

rejected

Fired each time an unsuccessful final (300-699) response is received. Note: This will also emit a failed event.

on('rejected', function (response, cause) {})

Name Type Description
response SIP.IncomingMessage The received response
cause String The reason phrase associated with the SIP response code.

failed

Fired when the request fails, whether due to an unsuccessful final response or due to timeout, transport, or other error.

on('failed', function (data) {})

Name Type Description
data Object A wrapper object containing the event data
data.code Number The status code of the received response, between 300 and 699, or 0 if the failure was not due to a received response.
data.response SIP.IncomingMessage|null The received response, or null if the failure was not due to a received response.
data.cause String The reason phrase associated with the SIP response code, or one of SIP.C.causes if the failure was not due to a received response.

connecting

Fired when ICE is starting to negotiate between the peers.

on('connecting', function () {})

There are no documented arguments for this event

cancel

Fired when the session was canceled by the client.

on('cancel', function() {})

There are no documented arguments for this event

refer

Fired when a REFER is received, and the user would like to handle the transfer at the application level. This event will not be emitted if it is not listened for. NOTE: This event does not exist in tagged release 0.5.0.

on('refer', function(request) {})

Name Type Description
request Object SIP.IncomingMessage instance of the received SIP REFER request.

referred

Fired when a REFER is received and the user wants SIP.js to handle the details of setting up the new session. This new session is set up in a generic way, and then emitted with the event. This event will not be emitted if it is not listened for. NOTE: In tagged release 0.5.0, this is how all REFERS are handled, and will always be emitted.

on('referred', function(request,newSession) {})

Name Type Description
request Object SIP.IncomingMessage instance of the received SIP REFER request.
newSession Object SIP.Session the new session created by the refer.

dtmf

Fired for an incoming or outgoing DTMF.

.on('dtmf', function(dtmf, request) {})

Name Type Description
dtmf Object SIP.Session.DTMF instance.
request Object SIP.IncomingMessage instance of the received SIP INFO request.

bye

Fired when a BYE is sent.

on('bye', function(request) {})

Name Type Description
request Object SIP.IncomingMessage instance of the received SIP BYE request.