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 isfalse
.
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 istrue
.useVideo
Boolean
to specify whether the call is intended to use video. Default value istrue
.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
andremoteView
) pointing to theHTMLVideoElement
(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. Defaulttext/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.