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 configuration = {
  'outbound_proxy_set': 'ws://sip-ws.example.com',
  'uri':                'sip:alice@example.com',
  'password':           'superpassword'
};

var coolPhone = new JsSIP.UA(configuration);

Instance Methods

start()

Connects to the WebSocket 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.

Throws

stop()

Saves the current registration state and disconnects from the WebSocket server after gracefully unregistering and terminating active sessions if any.

Throws

register()

Registers the UA. Not needed when register parameter is set to true in the UA Configuration Parameters.

Throws

unregister(all)

Unregisters the UA.

Parameters

all
Optional Boolean for unregistering all bindings of the same SIP user. Default value is false.

Throws

call(target, useAudio, useVideo, eventHandlers, views)

Makes an outgoing multimedia call.

Parameters

target
Destination of the call. String representing a destination username or a complete SIP URI.
useAudio
Boolean to specify whether the call is intended to use audio. Default value is true.
useVideo
Boolean to specify whether the call is intended to use video. Default value is true.
eventHandlers
Object of event handlers to be registered to each call event. Event handlers are optional. Define an event handler for each event you want to be notified about.
views
Object with two keys (selfView and remoteView) pointing to the HTMLVideoElement (HTML5 <video>) in which local and remote video will be shown.

Throws

Example

var useAudio = true;
var useVideo = true;

var views = {
  'selfView':   document.getElementById('my-video'),
  'remoteView': document.getElementById('peer-video')
};

var eventHandlers = {
  'connecting': function(e){ // Your code here },
  'progress':   function(e){ // Your code here },
  'failed':     function(e){ // Your code here },
  'started':    function(e){ // Your code here },
  'ended':      function(e){ // Your code here }
};

coolPhone.call('sip:bob@example.com', useAudio, useVideo, eventHandlers, views);

sendMessage(target, body, contentType="text/plain", eventHandlers=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.
body
Message content. String representing the body of the message.
contentType
Optional String representing the content-type of the body. Default text/plain.
eventHandlers
Object of event handlers to be registered to each message event. Event handlers are optional. Define an event handler for each event you want to be notified about.

Throws

Example

var contentType = "text/plain";

var text = 'Hello Bob!';

var eventHandlers = {
  'succeeded': function(e){ // Your code here },
  'failed':    function(e){ // Your code here };
};

coolPhone.sendMessage('sip:bob@example.com', text, contentType, eventHandlers);

isRegistered()

Returns true if the UA is registered, false otherwise.

isConnected()

Returns true if the WebSocket connection is established, false otherwise.

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.

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

connected

Fired when the WebSocket connection is established.

disconnected

Fired when the WebSocket connection attempt (or automatic re-attempt) fails.

registered

Fired for a successfull registration.

Event data fields

response
JsSIP.IncomingResponse instance of the received SIP 2XX response.

unregistered

Fired for a successfull unregistration.

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.

newSession

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