Class JsSIP.UA
JsSIP SIP User Agent class.
Instantiation
A User Agent is associated to a SIP user account. This class requires some configuration parameters for its initialization which are provided through a configuration object. Check the full UA Configuration Parameters list.
Instantiation of this class will raise an exception if any of the mandatory parameters is not defined or due to a malformed parameter value.
Throws
Example
var socket = new JsSIP.WebSocketInterface('wss://sip.example.com');
var configuration = {
sockets : [ socket ],
uri : 'sip:alice@example.com',
ha1 : '350fe29ce3890bd85d105998b0a95cf7',
realm : 'sip.example.com'
};
var ua = new JsSIP.UA(configuration);
Instance Methods
start
()
Connects to the signaling server and restores the previous state if previously stopped. For a fresh start, registers with the SIP domain if register
parameter in the UA’s configuration is set to true
.
stop
()
Saves the current registration state and disconnects from the signaling server after gracefully unregistering and terminating active sessions if any.
register
()
Registers the UA.
Note: If register
parameter is set to true
in UA Configuration Parameters, the UA will register automatically.
unregister
(options=null)
Unregisters the UA.
Parameters
options
- Optional
Object
with extra parameters (see below).
Fields in options
Object
all
- Optional
Boolean
for unregistering all bindings of the same SIP user. Default value isfalse
.
var options = {
all: true
};
ua.unregister(options);
registrator
()
Gets the JsSIP.Registrator
instance.
call
(target, options=null)
Makes an outgoing multimedia call.
Parameters
target
- Destination of the call.
String
representing a destination username or a complete SIP URI, or aJsSIP.URI
instance. options
- Optional
Object
with extra parameters (see below).
Fields in options
Object
mediaConstraints
Object
with two valid fields (audio
andvideo
) indicating whether the session is intended to use audio and/or video and the constraints to be used. Default value is bothaudio
andvideo
set totrue
.mediaStream
MediaStream
to transmit to the other end.pcConfig
Object
representing the RTCPeerConnectionRTCConfiguration
.rtcConstraints
Object
representing RTCPeerconnection constraints.rtcOfferConstraints
Object
representing constraints for RTCPeerconnectioncreateOffer()
.rtcAnswerConstraints
Object
representing constraints for RTCPeerconnectioncreateAnswer()
(to be used for future incoming reINVITE or UPDATE with SDP offer).eventHandlers
- Optional
Object
of event handlers to be registered to each call event. Define an event handler for each event you want to be notified about. extraHeaders
Array
ofStrings
with extra SIP headers for the INVITE request.anonymous
Boolean
field indicating whether the call should be done anonymously. Default value isfalse
.sessionTimersExpires
Number
(in seconds) for the default Session Timers interval (default value is 90, do not set a lower value).fromUserName
String
to override the user name in the From header. New!fromDisplayName
String
to override the display name in the From header. Overrides the UA configuration parameterdisplay_name
. New!
Example
// HTML5 <video> elements in which local and remote video will be shown
var views = {
'selfView': document.getElementById('my-video'),
'remoteView': document.getElementById('peer-video')
};
// Register callbacks to desired call events
var eventHandlers = {
'progress': function(data){ /* Your code here */ },
'failed': function(data){ /* Your code here */ },
'confirmed': function(data){ /* Your code here */ },
'ended': function(data){ /* Your code here */ }
};
var options = {
'eventHandlers': eventHandlers,
'extraHeaders': [ 'X-Foo: foo', 'X-Bar: bar' ],
'mediaConstraints': {'audio': true, 'video': true},
'pcConfig': {
'iceServers': [
{ 'urls': ['stun:a.example.com', 'stun:b.example.com'] },
{ 'urls': 'turn:example.com', 'username': 'foo', 'credential': ' 1234' }
]
}
};
ua.call('sip:bob@example.com', options);
sendMessage
(target, body, options=null)
Sends an instant message making use of SIP MESSAGE method.
Parameters
target
- Destination of the message.
String
representing a destination username or a complete SIP URI, or aJsSIP.URI
instance. body
- Message content.
String
representing the body of the message. options
- Optional
Object
with extra parameters (see below).
Fields in options
Object
contentType
- Optional
String
representing the content-type of the body. Defaulttext/plain
. eventHandlers
- Optional
Object
of event handlers to be registered to eachJsSIP.Message
event. Define an event handler for each event you want to be notified about. extraHeaders
- Optional
Array
ofStrings
with extra SIP headers for each MESSAGE request.
Example
var text = 'Hello Bob!';
var eventHandlers = {
'succeeded': function(data){ /* Your code here */ },
'failed': function(data){ /* Your code here */ };
};
var options = {
'eventHandlers': eventHandlers
};
ua.sendMessage('sip:bob@example.com', text, options);
terminateSessions
(options=null)
Terminates ongoing calls.
Parameters
options
- Optional
Object
with extra parameters as defined inJsSIP.RTCSession
for call termination.
isRegistered
()
Returns true
if the UA is registered, false
otherwise.
isConnected
()
Returns true
if the transport is connected, false
otherwise.
get
(parameter)
Retrieves the computed configuration parameter once in runtime. Currently the following values can be retrieved: authorization_user
, realm
, ha1
and authorization_jwt
.
parameter
- UA configuration parameter name.
set
(parameter, value)
Modifies the given UA configuration parameter in runtime (once started). Currently just authorization_user
, password
, realm
, ha1
, authorization_jwt
and display_name
can be modified.
Returns true
if the modifitation could be done.
parameter
- UA configuration parameter name.
value
- New value.
Events
JsSIP.UA
class defines a series of events. Each of them allows callback functions registration in order to let the user execute a handler for each given stimulus.
connecting
Fired for each transport connection attempt.
Event data
fields
socket
JsSIP.Socket
instance being connecting.attempts
Number
indicating the transport connection attempts.
connected
Fired when the transport connection is established.
Event data
fields
socket
JsSIP.Socket
instance which has connected.
disconnected
Fired when the transport connection attempt (or automatic re-attempt) fails.
Event data
fields
socket
JsSIP.Socket
instance.error
Boolean
indicating whether the socket disconnected due to an errorcode
- Optional
Number
indicating the socket disconnection code. reason
- Optional
String
indicating the socket disconnection reason.
registered
Fired for a successfull registration.
Event data
fields
response
JsSIP.IncomingResponse
instance of the received SIP 2XX response.
unregistered
Fired for an unregistration. This event is fired in the following scenarios:
- As a result of a unregistration request.
UA.unregister()
. - If being registered, a periodic re-registration fails.
Event data
fields
response
JsSIP.IncomingResponse
instance of the received SIP response for a (un)REGISTER SIP request.cause
null
for possitive response to un-REGISTER SIP request. In other case, one value of Failure and End Causes.
registrationFailed
Fired for a registration failure.
Event data
fields
response
JsSIP.IncomingResponse
instance of the received SIP negative response if the failure is generated by the recepcion of such response, null otherwise.cause
- One value of Failure and End Causes.
registrationExpiring
Fired a few seconds before the registration expires. If the application does not set any listener for this event, JsSIP will just re-register as usual.
If the application subscribes to this event, it’s responsible of calling ua.register()
within the registrationExpiring
event (otherwise the registration will expire).
This event provides the application with a chance to perform async operations before re-registering. Useful for those environments using an externally obtained “token” within a custom SIP header in the REGISTER request.
newRTCSession
Fired for an incoming or outgoing session/call.
Event data
fields for an incoming session
originator
- ‘remote’
String
. The new session is generated by the remote peer. session
JsSIP.RTCSession
instance of the session.request
JsSIP.IncomingRequest
instance of the received INVITE request.
Event data
fields for an outgoing session
originator
- ‘local’
String
. The new session is generated by the local user. session
JsSIP.RTCSession
instance of the session.request
JsSIP.OutgoingRequest
instance of the outgoing INVITE request.
newMessage
Fired for an incoming or outgoing MESSAGE request.
Event data
fields for an incoming message
originator
- ‘remote’
String
. The new message is generated by the remote peer. message
JsSIP.Message
instance.request
JsSIP.IncomingRequest
instance of the received MESSAGE request.
Event data
fields for an outgoing message
originator
- ‘local’
String
. The new message is generated by the local user. message
JsSIP.Message
instance.request
JsSIP.OutgoingRequest
instance of the outgoing MESSAGE request.
sipEvent
Fired for an incoming out of dialog NOTIFY request.
Event data
fields
event
Event
instance. See below.request
JsSIP.IncomingRequest
instance of the received NOTIFY request.
event
parameter
event
- ‘event-type’ defined in the Event header field.
params
Object
containing the parameters received in the Event header field.