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
- Instance Attributes
- Instance Methods
- Instance Methods (Outbound/Client)
- Instance Methods (Inbound/Server)
- Events
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. |