/ home / the Javascript SIP library / Documentation / 0.5.x / API / JsSIP.UA

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 = {
  'ws_servers':         '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.

stop()

Saves the current registration state and disconnects from the WebSocket 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 is false.
var options = {
  all: true
};

coolPhone.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 a JsSIP.URI instance.
options
Optional Object with extra parameters (see below).

Fields in options Object

mediaConstraints
Object with two valid fields (audio and video) indicating whether the session is intended to use audio and/or video and the constraints to be used. Default value is both audio and video set to true.
mediaStream
MediaStream to transmit to the other end.
RTCConstraints
Object representing RTCPeerconnection constraints.
RTCOfferConstraints
Object representing constraints for RTCPeerconnection createOffer.
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 of Strings with extra SIP headers for the INVITE request.
anonymous
Boolean field indicating whether the call should be done anonymously. Default value is false.
stun_servers
stun_servers as defined in UA Configuration Parameters
turn_servers
stun_servers as defined in UA Configuration Parameters

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(e){ /* Your code here */ },
  'failed':     function(e){ /* Your code here */ },
  'started':    function(e){
    var rtcSession = e.data.session;

    // Attach local stream to selfView
    if (rtcSession.getLocalStreams().length > 0) {
      selfView.src = window.URL.createObjectURL(rtcSession.getLocalStreams()[0]);
    }

    // Attach remote stream to remoteView
    if (rtcSession.getRemoteStreams().length > 0) {
      remoteView.src = window.URL.createObjectURL(rtcSession.getRemoteStreams()[0]);
    }
  },
  'ended':      function(e){ /* Your code here */ }
};

var options = {
  'eventHandlers': eventHandlers,
  'extraHeaders': [ 'X-Foo: foo', 'X-Bar: bar' ],
  'mediaConstraints': {'audio': true, 'video': true}
};

coolPhone.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 a JsSIP.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. Default text/plain.
eventHandlers
Optional Object of event handlers to be registered to each JsSIP.Message event. Define an event handler for each event you want to be notified about.
extraHeaders
Optional Array of Strings with extra SIP headers for each MESSAGE request.

Example

var text = 'Hello Bob!';

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

var options = {
  'eventHandlers': eventHandlers
};

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

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.

connecting

Fired for each WebSocket connection attempt.

Event data fields

transport
WebSocket connection.
attempts
Number indicating the connection attempts to the transport.

connected

Fired when the WebSocket connection is established.

Event data fields

transport
WebSocket connection.

disconnected

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

Event data fields

transport
WebSocket connection.
code
Number indicating the WebSocket disconnection code.
reason
String indicating the WebSocket 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.

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.

/ home / the Javascript SIP library / Documentation / 0.5.x / API / JsSIP.UA