Class JsSIP.UA

JsSIP SIP User Agent class.

• Instantiation
• Instance Methods
  • start()
  • stop()
  • register()
  • unregister()
  • call()
  • sendMessage()
  • isRegistered()
  • isConnected()
• Events
  • connected
  • disconnected
  • registered
  • unregistered
  • registrationFailed
  • newSession
  • newMessage

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

• CONFIGURATION_ERROR

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

• NOT_READY_ERROR

stop()

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

Throws

• NOT_READY_ERROR

register()

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

Throws

• NOT_READY_ERROR

unregister(all)

Unregisters the UA.

Parameters

all

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

Throws

• NOT_READY_ERROR

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

• INVALID_TARGET_ERROR
• NOT_READY_ERROR
• WEBRTC_NOT_SUPPORTED_ERROR

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

• INVALID_TARGET_ERROR
• NOT_READY_ERROR

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.