SIPML5

https://www.doubango.org/sipml5/docgen/
Admin
SIPML5 is a JavaScript API for building plugin-free NGN (VoIP, messaging, video conferencing)...
Tokens:28,159
Snippets:141
Trust Score:9.1
Update:11 months ago
Show doc for...
Tokens:
Raw
### Start BFCP Share

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Starts sharing your entire desktop or an App using BFCP. Requires the webrtc4all plugin. Available since version 2.0.0.

```APIDOC
## POST /api/session/call/bfcp/share/start

### Description
Starts sharing your entire desktop or an App using BFCP. Requires webrt4all plugin.

### Method
POST

### Endpoint
/api/session/call/bfcp/share/start

### Parameters
#### Request Body
- **configuration** (SIPml.Session.Configuration) - Optional - Configuration value.

### Response
#### Success Response (200)
- **result** (Integer) - 0 if successful; otherwise nonzero

#### Response Example
{
  "result": 0
}
```

--------------------------------

### Initialize Engine, Start Stack, and Make Video Call (JavaScript)

Source: https://www.doubango.org/sipml5/docgen/index

This code snippet demonstrates how to initialize the SIPML5 engine, start the SIP stack, and initiate an audio/video call from 'bob' to 'alice'. It requires the SIPml library to be loaded and specifies the realm, user identity, and password for the SIP stack.

```javascript
SIPml.init(
        function(e){
            var stack =  new SIPml.Stack({realm: 'example.org', impi: 'bob', impu: 'sip:bob@example.org', password: 'mysecret',
                events_listener: { events: 'started', listener: function(e){
                            var callSession = stack.newSession('call-audiovideo', {
                                    video_local: document.getElementById('video-local'),
                                    video_remote: document.getElementById('video-remote'),
                                    audio_remote: document.getElementById('audio-remote')
                                });
                            callSession.call('alice');
                        } 
                    }
            });
            stack.start();
        }
);
    

```

--------------------------------

### Creating SIP Stack with SIPml5 in JavaScript

Source: https://www.doubango.org/sipml5/docgen/index

This snippet initializes a new SIP stack using SIPml5, which is required before making calls or sending messages. It sets mandatory parameters like realm, impi, impu, and optional ones like password and proxy URLs. The stack starts asynchronously, using an event listener to handle states like 'started' for proceeding to login.

```javascript
var sipStack;
var eventsListener = function(e){
    if(e.type == 'started'){
        login();
    }
    else if(e.type == 'i_new_message'){ // incoming new SIP MESSAGE (SMS-like)
        acceptMessage(e);
    }
    else if(e.type == 'i_new_call'){ // incoming audio/video call
        acceptCall(e);
    }
}

function createSipStack(){
    sipStack = new SIPml.Stack({
            realm: 'example.org', // mandatory: domain name
            impi: 'bob', // mandatory: authorization name (IMS Private Identity)
            impu: 'sip:bob@example.org', // mandatory: valid SIP Uri (IMS Public Identity)
            password: 'mysecret', // optional
            display_name: 'Bob legend', // optional
            websocket_proxy_url: 'wss://sipml5.org:10062', // optional
            outbound_proxy_url: 'udp://example.org:5060', // optional
            enable_rtcweb_breaker: false, // optional
            events_listener: { events: '*', listener: eventsListener }, // optional: '*' means all events
            sip_headers: [ // optional
                    { name: 'User-Agent', value: 'IM-client/OMA1.0 sipML5-v1.0.0.0' },
                    { name: 'Organization', value: 'Doubango Telecom' }
            ]
        }
    );
}
sipStack.start();
```

--------------------------------

### Create SIP Stack Configuration

Source: https://www.doubango.org/sipml5/docgen/symbols/SIPml.Stack

Example of configuring a SIP stack using SIPml.Stack.Configuration. Includes settings for realm, authentication, WebSocket proxy, ICE servers, and optional features like RTCWeb Breaker and Click2Call.

```javascript
var configuration = {
        realm: 'example.org',
        impi: 'bob',
        impu: 'sip:bob@example.org',
        password: 'mysecret', // optional
        display_name: 'I Am Legend', // optional
        websocket_proxy_url: 'ws://192.168.0.10:5060', // optional
        outbound_proxy_url: 'udp://192.168.0.12:5060', // optional
        ice_servers: [{ url: 'stun:stun.l.google.com:19302'}, { url:'turn:user@numb.viagenie.ca', credential:'myPassword'}], // optional
        enable_rtcweb_breaker: true, // optional
        enable_click2call: false, // optional
        enable_early_ims: true, // optional
        events_listener: { events: '*', listener: listenerFunc }, // optional
        sip_headers: [ //optional
            {name: 'User-Agent', value: 'IM-client/OMA1.0 sipML5-v1.0.89.0'}, 
            {name: 'Organization', value: 'Doubango Telecom'}
        ]
    };
```

--------------------------------

### Start BFCP Screen Sharing

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Initiates desktop or application sharing using BFCP, requiring the webrtc4all plugin. Accepts an optional configuration object. Returns an integer status code or throws ERR_NOT_READY/ERR_NOT_SUPPORTED.

```javascript
SIPml.Session.Call.prototype.startBfcpShare = function (o_conf) {
    if (SIPml.getWebRtcType() != 'w4a') {
        throw new Error("ERR_NOT_SUPPORTED: BFCP sharing requires webrtc4all plugin");
    }
    this.setConfiguration(o_conf);
    return this.o_session.start_bfcp_share();
}
```

--------------------------------

### SIP Session Configuration Example

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

This JavaScript code snippet demonstrates how to configure a SIP session. It includes settings for expiration, audio/video elements, SIP capabilities, and custom SIP headers.

```javascript
var configuration = {
    expires: 200,
    audio_remote: document.getElementById('audio_remote'), // <audio id="audio_remote" .../>
    video_local: document.getElementById('video_local'),  // <video id="video_local" .../>
    video_remote: document.getElementById('video_remote'),  // <video id="video_remote" .../>
    sip_caps: [
                    {name: '+g.oma.sip-im'},
                    {name: '+sip.ice'},
                    {name: 'language', value: '"en,fr"'}
            ],
    sip_headers: [
                    {name: 'What', value: 'Audio/Video call', session: false},
                    {name: 'Organization', value: 'Doubango Telecom', session: false}
            ]
}
```

--------------------------------

### Initialize SIPml.Stack with Configuration - JavaScript

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

This example demonstrates how to initialize the SIPml.Stack object with a configuration object. The configuration includes realm, IMPI, IMPU, and optional parameters like password, display name, and proxy URLs.

```JavaScript
var listenerFunc = function(e){
    console.info('stack event = ' + e.type);
    // Please check <a href="SIPml.EventTarget.html#SIPml.EventTarget.Stack">this link</a> for more information on all supported events.
}

var o_stack = new SIPml.Stack({
        realm: 'example.org',
        impi: 'bob',
        impu: 'sip:bob@example.org',
        password: 'mysecret', // optional
        display_name: 'I Am Legend', // optional
        websocket_proxy_url: 'ws://192.168.0.10:5060', // optional
        outbound_proxy_url: 'udp://192.168.0.12:5060', // optional
        ice_servers: [{ url: 'stun:stun.l.google.com:19302'}, { url:'turn:user@numb.viagenie.ca', credential:'myPassword'}], // optional
        bandwidth: { audio:64, video:512 }, // optional
        video_size: { minWidth:640, minHeight:480, maxWidth:1920, maxHeight:1080 }, // optional
        enable_rtcweb_breaker: true, // optional
        enable_click2call: false, // optional
        events_listener: { events: '*', listener: listenerFunc }, //optional
        sip_headers: [ //optional
            {name: 'User-Agent', value: 'IM-client/OMA1.0 sipML5-v1.0.89.0'}, 
            {name: 'Organization', value: 'Doubango Telecom'}
        ]
    }
);
```

--------------------------------

### Start SIP Stack in JavaScript

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Starts the SIP stack and connects the network transport to the WebSocket server without sending any SIP request. This function must be called before any SIP operations. It is asynchronous, and the stack is not immediately started upon calling.

```javascript
SIPml.Stack.prototype.start = function () {
    return this.o_stack.start();
}
```

--------------------------------

### Get webrtc4all Plugin Version (JavaScript)

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Retrieves the version name of the installed webrtc4all plugin. The SIPml engine must be initialized before calling this function. Throws ERR_NOT_INITIALIZED if the engine is not ready.

```javascript
SIPml.getWebRtc4AllVersion = function () {
    if (!SIPml.isInitialized()) {
        throw new Error("ERR_NOT_INITIALIZED: Engine not initialized yet. Please call 'SIPml.init()' first");
    }
    return SIPml.s_webrtc4all_version;
};
```

--------------------------------

### Get Running Applications (webrt4all)

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Retrieves a list of running applications, a feature that requires the webrt4all plugin. The output is a formatted string containing details about each application, including ID, description, and icon data. It throws errors if the system is not ready or if the plugin is not supported.

```javascript
/** 
Gets the list of running apps. Requires webrt4all plugin.
@since version 2.0.0
@returns {String} the the list of running apps. Format: <i>(base64($$WindowID$$=str(...)$$Description$$=str(...)$$IconData$$=base64(...)$$IconType$$=str(...)))*</i>
@throws {ERR_NOT_READY | ERR_NOT_SUPPORTED} <font color="red">ERR_NOT_READY</font> | <font color="red">ERR_NOT_SUPPORTED</font>
*/
SIPml.getRunningApps = function () {
    if (SIPml.getWebRtcType() != 'w4a') {
        throw new Error("ERR_NOT_SUPPORTED: requires webrtc4all plugin");
    }
    return WebRtc4all_GetPlugin().runningApps();
}
```

--------------------------------

### Create SIPml subscription session and handle NOTIFY events

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Demonstrates how to instantiate a SIPml subscription session, register an event listener for incoming NOTIFY requests, and start a presence subscription for a user. Requires a SIPml.Stack instance named `stack`. Returns a session object used for further actions.

```JavaScript

```

--------------------------------

### Start Native Code Debugging (webrt4all)

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Initiates debugging for the native C/C++ code. This feature requires the webrt4all plugin and is intended for advanced debugging scenarios. On Windows, the log file is located at 'C:\\Users\\<YOUR LOGIN>\\AppData\\Local\\Temp\\Low\\webrtc4all.log'.

```javascript
/** 
Starts debugging the native (C/C++) code. Requires webrt4all plugin.
On Windows, the output file should be at <b>C:\\Users\\<YOUR LOGIN>\\AppData\\Local\\Temp\\Low\\webrtc4all.log</b>.
Starting the native debug isn't recommended and must be done to track issues only.
@since version 2.0.0
*/
SIPml.startNativeDebug = function () {
    WebRtc4all_GetPlugin().startDebug();
}
```

--------------------------------

### Get System Friendly Name (JavaScript)

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Retrieves the system-friendly name. Requires the SIPml engine to be initialized. Throws an error if not initialized.

```javascript
SIPml.getSystemFriendlyName = function () {
    if (!SIPml.isInitialized()) {
        throw new Error("ERR_NOT_INITIALIZED: Engine not initialized yet. Please call 'SIPml.init()' first");
    }
    return SIPml.s_system_friendly_name;
};
```

--------------------------------

### Get Navigator Version (JavaScript)

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Obtains the version of the web browser. This function requires the SIPml engine to be initialized. It returns the browser version string and throws an error if initialization is not complete.

```javascript
SIPml.getNavigatorVersion = function () {
    if (!SIPml.isInitialized()) {
        throw new Error("ERR_NOT_INITIALIZED: Engine not initialized yet. Please call 'SIPml.init()' first");
    }
    return SIPml.s_navigator_version;
};
```

--------------------------------

### Create SIP Message (SMS) Session using SIPml

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Demonstrates how to create a new SIP MESSAGE session using the stack.newSession function. It shows example configurations for setting the session type to 'message'.

```javascript
var session = stack.newSession('message');
```

--------------------------------

### Get Operating System Friendly Name (JavaScript)

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Returns the user-friendly name of the Operating System (e.g., 'windows', 'mac'). This function requires the SIPml engine to be initialized. It will throw ERR_NOT_INITIALIZED if the engine is not yet initialized.

```javascript
SIPml.getNavigatorOsFriendlyName = function () {
    if (!SIPml.isInitialized()) {
        throw new Error("ERR_NOT_INITIALIZED: Engine not initialized yet. Please call 'SIPml.init()' first");
    }
    return SIPml.s_navigator_os_friendly_name;
};
```

--------------------------------

### Add Event Listener to SIPml.EventTarget (JavaScript)

Source: https://www.doubango.org/sipml5/docgen/symbols/SIPml

Demonstrates how to add event listeners to a SIPml.EventTarget object. It shows examples for listening to a single event, multiple events, or all events using the addEventListener method. This method is crucial for reacting to state changes and incoming events within the SIPml framework.

```javascript
// listen for a single event
this.addEventListener('started', function(e){
    console.info("'started' event fired");
});
// or listen for two or more events
this.addEventListener(['started', 'stopped'], function(e){
    console.info("'"+e.type+"' event fired");
});
// or listen for all events
this.addEventListener('*', function(e){
    console.info("'"+e.type+"' event fired");
});
```

--------------------------------

### SIP Session Get ID Method

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

This JavaScript method retrieves the unique identifier for a SIP session. It accesses the private wrapped session object to get its ID.

```javascript
SIPml.Session.prototype.getId = function () {
    return this.o_session.get_id();
}
```

--------------------------------

### Initialization and Readiness Checks

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Provides functions to check the initialization status, WebRTC support, and media stream availability of the SIPml engine.

```APIDOC
## SIPml.init()

### Description
Initializes the SIPml engine. This function must be called before any other SIPml functions.

### Method
`SIPml.init(successCallback, errorCallback)`

### Parameters
- **successCallback** (CallbackFunction) - Optional. A function to call when the stack finishes initializing and becomes ready.
- **errorCallback** (CallbackFunction) - Optional. A function to call when initialization fails.

### Request Example
```javascript
SIPml.init(function(e) { console.info('engine is ready'); }, function(e) { console.info('Error: ' + e.message); });
```

## SIPml.isReady()

### Description
Checks if the SIPml engine is ready to be used. This means it has been initialized, WebRTC is supported, and a valid media stream is available.

### Method
`SIPml.isReady()`

### Returns
- **Boolean**: `true` if the engine is ready; otherwise `false`.

### Throws
- **ERR_NOT_INITIALIZED**: If the engine has not been initialized using `SIPml.init()`.

## SIPml.isInitialized()

### Description
Checks whether the SIPml engine has been initialized.

### Method
`SIPml.isInitialized()`

### Returns
- **Boolean**: `true` if the engine is initialized; otherwise `false`.
```

--------------------------------

### Initialize SIPml Engine in JavaScript

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

This code snippet handles the initialization of the SIPml engine, setting flags for initialization status and logging info. It requires WebRTC support checks and calls a success callback if initialization succeeds, or an error callback with a description if it fails. Inputs include success and error callbacks; outputs are callback executions.

```javascript
SIPml.b_initialized = true;
SIPml.b_initializing = false;
tsk_utils_log_info("Engine initialized");
if (successCallback) {
    successCallback({});
}
else {
    if (errorCallback) {
        var s_description = !SIPml.b_webrtc_supported ? "WebRTC not supported" : (!SIPml.b_have_media_stream ? "getUserMedia not supported" : "Internal error");
        errorCallback({ description: s_description });
    }
}
```

--------------------------------

### Initialize SIPML5 Engine (JavaScript)

Source: https://www.doubango.org/sipml5/docgen/index

This code snippet shows how to initialize the SIPML5 engine using the SIPml.init function. It takes two callback functions: one for successful initialization and another for handling errors. The successful callback typically proceeds to create the SIP stack.

```javascript
var readyCallback = function(e){
    createSipStack(); // see next section
};
var errorCallback = function(e){
    console.error('Failed to initialize the engine: ' + e.message);
}
SIPml.init(readyCallback, errorCallback);


```

--------------------------------

### Unregister SIP User

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Sends a SIP REGISTER request with an expiration time of 0 to log out the user. This method accepts optional configuration and can throw ERR_INVALID_STATE if the stack is not started.

```javascript
SIPml.Session.Registration.prototype.unregister = function (o_conf) {
    // FIXME: raise error if stack not started
    this.setConfiguration(o_conf);
}
```

--------------------------------

### Initiate an Audio/Video Call

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

This code snippet demonstrates how to create a new audio-video call session using SIPML5. It configures local and remote video/audio elements, sets SIP capabilities, and initiates the call to a specified user.

```javascript
var o_audiovideo = this.newSession('call-audiovideo', {
            video_local: document.getElementById('video_local'),
            video_remote: document.getElementById('video_remote'),
            audio_remote: document.getElementById('audio_remote'),
            sip_caps: [
                    {name: '+g.oma.sip-im'},
                    {name: '+sip.ice'},
                    {name: 'language', value: '"en,fr"'}
            ],
            sip_headers: [
                    {name: 'What', value: 'Audio/Video call', session: false},
                    {name: 'Organization', value: 'Doubango Telecom', session: false}
            ]
        });
o_audiovideo.call('alice'); // call alice
```

--------------------------------

### Initiate Audio/Video Call with SIPml.js

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

This snippet demonstrates how to initiate an audio/video call using the SIPml.js library. It requires specifying the destination, local and remote video elements, remote audio element, and event listeners. The function 'stack.newSession' is used to create the session, and 'session.call' is used to make the call.

```javascript
var listenerFunc = function(e){
    console.info('session event = ' + e.type);
}
var session = stack.newSession('call-audiovideo', {
            video_local: document.getElementById('video-local'), // <video id="video-local" .../>
            video_remote: document.getElementById('video-remote'), // <video id="video-remote" .../>
            audio_remote: document.getElementById('audio-remote'), // <audio id="audio-remote" .../>
            events_listener: { events: '*', listener: listenerFunc },
            sip_caps: [
                            { name: '+g.oma.sip-im' },
                            { name: '+sip.ice' },
                            { name: 'language', value: '"en,fr"' }
                        ]
        });
session.call('johndoe', {
            video_local: document.getElementById('video-local'), // <video id="video-local" .../>
            video_remote: document.getElementById('video-remote'), // <video id="video-remote" .../>
            audio_remote: document.getElementById('audio-remote'), // <audio id="audio-remote" .../>
            events_listener: { events: '*', listener: listenerFunc },
            sip_caps: [
                            { name: '+g.oma.sip-im' },
                            { name: '+sip.ice' },
                            { name: 'language', value: '"en,fr"' }
                        ]
        });

```

--------------------------------

### Making Audio/Video Calls with SIPml5 in JavaScript

Source: https://www.doubango.org/sipml5/docgen/index

This snippet creates an audio/video call session using the SIP stack, attaching local and remote video/audio elements. It supports making calls to a SIP URI like 'johndoe' and handles session events. Registration is optional but advised; limitations include needing HTML elements for media.

```javascript
var callSession;
var eventsListener = function(e){
    console.info('session event = ' + e.type);
}
var makeCall = function(){
    callSession = sipStack.newSession('call-audiovideo', {
        video_local: document.getElementById('video-local'),
        video_remote: document.getElementById('video-remote'),
        audio_remote: document.getElementById('audio-remote'),
        events_listener: { events: '*', listener: eventsListener } // optional: '*' means all events
    });
    callSession.call('johndoe');
}
```

--------------------------------

### Register SIP User

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Sends a SIP REGISTER request to log in a user. Automatic refresh requests are handled based on the expiration time. This method accepts optional configuration and can throw ERR_INVALID_STATE if the stack is not started.

```javascript
SIPml.Session.Registration.prototype.register = function (o_conf) {
    // FIXME: apply o_configuration
    // FIXME: raise error if stack not started
    this.setConfiguration(o_conf);
    return this.o_session.register();
}
```

--------------------------------

### Initialize SIPml Engine

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Initializes the SIPml engine, which is a mandatory step before using any other functions. It accepts optional callbacks for success and error scenarios. This function also performs various checks for WebRTC and related technologies.

```javascript
/**
    * Initialize the engine. <b>You must call this function before any other.</b>.
    * @param {CallbackFunction} [readyCallback] Optional callback function to call when the stack finish initializing and become ready.
    * @param {CallbackFunction} [errorCallback] Optional callback function to call when initialization fails.
    *
    * @example
    * SIPml.init(function(e){ console.info('engine is ready'); }, function(e){ console.info('Error: ' + e.message); });
    * @static
    */
SIPml.init = function (successCallback, errorCallback) {
    if (!SIPml.b_initialized && !SIPml.b_initializing) {
        SIPml.b_initializing = true;
        tsk_utils_init_webrtc();

        tsk_utils_log_info('User-Agent=' + (navigator.userAgent || "unknown"));

        SIPml.b_have_media_stream = tsk_utils_have_stream();
        SIPml.b_webrtc_supported = tsk_utils_have_webrtc();
        SIPml.b_webrtc4all_supported = tsk_utils_have_webrtc4all();
        SIPml.s_webrtc4all_version = tsk_utils_webrtc4all_get_version();
        SIPml.s_navigator_friendly_name = tsk_utils_get_navigator_friendly_name();
        SIPml.s_system_friendly_name = tsk_utils_get_system_friendly_name();

        // prints whether WebSocket is supported
        tsk_utils_log_info("WebSocket supported = " + (SIPml.isWebSocketSupported() ? "yes" : "no"));

        // check webrtc4all version
        if (tsk_utils_have_webrtc4all()) {
            tsk_utils_log_info("WebRTC type = " + WebRtc4all_GetType() + " version = " + tsk_utils_webrtc4all_get_version());
            if (SIPml.s_webrtc4all_version != '1.35.981') {
                SIPml.b_webrtc4all_plugin_outdated = true;
            }
        }

        // prints navigator friendly name
        tsk_utils_log_info("Navigator friendly name = " + SIPml.s_navigator_friendly_name);

        // gets navigator version
        if (SIPml.s_navigator_friendly_name == 'ie') {
            var re = new RegExp("MSIE ([0-9]{1,}[.0-9]{0,})");
            if (re.exec(navigator.userAgent) != null) {
                SIPml.s_navigator_version = RegExp.$1;
            }
        }

        // prints OS friendly name
        tsk_utils_log_info("OS friendly name = " + SIPml.s_system_friendly_name);
        // prints support for WebRTC (native or plugin)
        tsk_utils_log_info("Have WebRTC = " + (tsk_utils_have_webrtc() ? "yes" : "false"));
        // prints support for getUserMedia
        tsk_utils_log_info("Have GUM = " + (tsk_utils_have_stream() ? "yes" : "false"));

        // checks for WebRTC support
        if (!tsk_utils_have_webrtc()) {
            // is it chrome?
            if (SIPml.s_navigator_friendly_name == "chrome") {
                SIPml.b_navigator_outdated = true;
                return;
            }

            // for now the plugins (WebRTC4all only works on Windows)
            if (SIPml.s_system_friendly_name == 'win' || SIPml.s_system_friendly_name == 'windows') {
                // Internet explorer
                if (SIPml.s_navigator_friendly_name == 'ie') {
                    // Check for IE version 
                    var rv = -1;
                    var ua = navigator.userAgent;
                    var re = new RegExp("MSIE ([0-9]{1,}[.0-9]{0,})");
                    if (re.exec(ua) != null) {
                        rv = parseFloat(RegExp.$1);
                    }
                    if (rv < 9.0) {
                        SIPml.b_navigator_outdated = true;
                        return;
                    }

                    // break page loading ('window.location' won't stop JS execution)
                    if (!tsk_utils_have_webrtc4all()) {
                        return;
                    }
                }
            }
        }

        if (SIPml.b_webrtc_supported && SIPml.b_have_media_stream) {
            // ... initialization continues ...
        }
    }
}
```

--------------------------------

### Get Navigator Friendly Name (JavaScript)

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Retrieves the user-friendly name of the web browser (e.g., 'chrome', 'firefox'). The SIPml engine must be initialized prior to calling this function. An error is thrown if the engine is not initialized.

```javascript
SIPml.getNavigatorFriendlyName = function () {
    if (!SIPml.isInitialized()) {
        throw new Error("ERR_NOT_INITIALIZED: Engine not initialized yet. Please call 'SIPml.init()' first");
    }
    return SIPml.s_navigator_friendly_name;
};
```

--------------------------------

### Get Current WebRTC Type

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Retrieves the type of WebRTC implementation currently in use. This is useful for understanding which WebRTC backend is active (e.g., native, w4a, erisson). It relies on the `WebRtc4all_GetType` function and `WebRtcType_e` enum.

```javascript
/** 
Gets the current WebRTC type being used.
@since version 1.4.217
@returns {String} the WebRTC type. Possible values: <i>native</i>, <i>w4a</i>, <i>erisson</i> or <i>unknown</i>.
*/
SIPml.getWebRtcType = function () {
    switch (WebRtc4all_GetType()) {
        case WebRtcType_e.W4A: case WebRtcType_e.IE: case WebRtcType_e.NPAPI: return "w4a";
        case WebRtcType_e.ERICSSON: return "erisson";
        case WebRtcType_e.NATIVE: return "native";
        default: return "unknown";
    }
}
```

--------------------------------

### Check SIPml Engine Readiness

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Checks if the SIPml engine is fully ready for operation. This includes verifying that the engine is initialized, WebRTC is supported, and a valid media stream is available. It throws an error if the engine has not been initialized.

```javascript
/**
    * Checks whether the engine is ready or not.
    * @static
    * @returns {Boolean} <i>true</i> if the engine is ready; otherwise <i>false</i>
    * @throws {ERR_NOT_INITIALIZED} <font color="red">ERR_NOT_INITIALIZED</font> if the engine is not <a href="#.init">initialized</a>.
    */
SIPml.isReady = function () {
    return (SIPml.isInitialized() && SIPml.isWebRtcSupported() && SIPml.haveMediaStream());
}
```

--------------------------------

### Registering and Logging In with SIPml5 in JavaScript

Source: https://www.doubango.org/sipml5/docgen/index

This code handles SIP registration to the server, which is optional but recommended for non-p2p modes. It creates a register session and calls register() on it, using an event listener to detect connection and trigger actions like making calls or sending messages. Inputs include the SIP stack instance; outputs are session events like 'connected'.

```javascript
var registerSession;
var eventsListener = function(e){
    console.info('session event = ' + e.type);
    if(e.type == 'connected' && e.session == registerSession){
        makeCall();
        sendMessage();
        publishPresence();
        subscribePresence('johndoe'); // watch johndoe's presence status change
    }
}
var login = function(){
    registerSession = sipStack.newSession('register', {
        events_listener: { events: '*', listener: eventsListener } // optional: '*' means all events
    });
    registerSession.register();
}
```

--------------------------------

### Create SIP Publish Session using SIPml

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Illustrates the creation of a SIP PUBLISH session for presence status publication. It shows how to configure parameters like 'expires', 'events_listener', 'sip_headers', and 'sip_caps' when creating the session via stack.newSession.

```javascript
var session = stack.newSession('publish', {
                            expires: 200,
                            events_listener: { events: '*', listener: function(e){} },
                            sip_headers: [
                                          { name: 'Event', value: 'presence' } // very important
                                ],
                            sip_caps: [
                                        { name: '+g.oma.sip-im', value: null },
                                        { name: '+audio', value: null },
                                        { name: 'language', value: '"en,fr"' }
                                ]
                        });
    SIPml.Session.call(this, o_session, o_conf);
    // set destination to ourself (https://groups.google.com/forum/#!topic/doubango/XKWTQ9TgjPU)
```

--------------------------------

### Get Call Transfer Destination Friendly Name

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Retrieves the friendly display name of the destination for a call transfer. It parses the SIP message headers to extract the 'Refer-To' header and returns either the display name or the username from the URI.

```javascript
SIPml.Session.Event.prototype.getTransferDestinationFriendlyName = function () {
    var o_message = this.o_event ? this.o_event.get_message() : null;
    if (o_message) {
        var o_hdr_Refer_To = o_message.get_header(tsip_header_type_e.Refer_To);
        if (o_hdr_Refer_To && o_hdr_Refer_To.o_uri) {
            return (o_hdr_Refer_To.s_display_name ? o_hdr_Refer_To.s_display_name : o_hdr_Refer_To.o_uri.s_user_name);
        }
    }
    return null;
}
```

--------------------------------

### Initialize SIP Stack Configuration

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Configures and initializes the SIP stack based on provided options. It determines the correct port and proxy server, dynamically adjusting based on whether RTCWEB breaker is enabled or if the protocol is HTTPS. The stack is then created and its configuration is set.

```javascript
    // port and host will be updated using the result from DNS SRV(NAPTR(realm))
    i_port = 5060;
    s_proxy = o_conf.realm;
} else {
    // there are at least 5 servers running on the cloud.
    // we will connect to one of them and let the balancer to choose the right one (less connected sockets)
    // each port can accept up to 65K connections which means that the cloud can manage 325K active connections
    // the number of port will be increased or decreased based on the current trafic
    // 
    // webrtc2sip 2.2+ (Doubango): 
    //      WS: 10060, 11060, 12060, 13060, 14060
    //      WSS: 10062, 11062, 12062, 13062, 14062
    //
    i_port = ((o_conf.enable_rtcweb_breaker || (window.location && window.location.protocol == "https:")) ? 10062 : 10060) + (((new Date().getTime()) % 5) * 1000);
    s_proxy = "ns313841.ovh.net";
}

// create the stack
this.o_stack = new tsip_stack(o_conf.realm, o_conf.impi, o_conf.impu, s_proxy, i_port);
this.o_stack.oStack = this;
// set configurations
this.setConfiguration(o_conf);
```

--------------------------------

### Get Remote Party Friendly Name

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Retrieves a human-readable name for the remote party in a SIP session. It extracts the display name if available, otherwise uses the username part of the SIP URI. This simplifies user identification compared to raw SIP URIs.

```javascript
SIPml.Session.prototype.getRemoteFriendlyName = function () {
    var o_uri = this.o_session.b_local ? this.o_session.o_uri_to : this.o_session.o_uri_from;
    return o_uri.s_display_name ? o_uri.s_display_name : o_uri.s_user_name;
}
```

--------------------------------

### Configure Session Bandwidth and Video Size

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Sets the bandwidth and video size for a SIP session. It allows configuration of audio and video bandwidth, as well as minimum and maximum video dimensions. Dependencies include the SIPml library and potentially configuration objects for bandwidth and video size.

```javascript
o_session.set(
            tsip_session.prototype.SetBandwidth(o_conf.bandwidth ? o_conf.bandwidth : { audio: undefined, video: undefined }),
            tsip_session.prototype.SetVideoSize(o_conf.video_size ? o_conf.video_size : { minWidth: undefined, minHeight: undefined, maxWidth: undefined, maxHeight: undefined }),
            tsip_session.prototype.SetScreencastWindowID(o_conf.screencast_window_id ? o_conf.screencast_window_id : 0)
        );
```

--------------------------------

### Implement SIPml subscription method (subscribe)

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Defines the `subscribe` function for `SIPml.Session.Subscribe` that validates the target, applies configuration, sets the destination, and sends a SUBSCRIBE request. Throws errors for invalid parameters or if the stack is not ready. Returns an integer status code.

```JavaScript
SIPml.Session.Subscribe.prototype.subscribe = function (s_to, o_conf) {
    if (tsk_string_is_null_or_empty(s_to)) {
        throw new Error("ERR_INVALID_PARAMETER_VALUE: 'to' must not be null");
    }
    // set destination
    this.o_session.set(tsip_session.prototype.SetToStr(s_to));
    // apply configuration values
    this.setConfiguration(o_conf);
    // sends the PUBLISH request
    return this.o_session.subscribe();
};
```

--------------------------------

### Register SIP Session

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

This snippet shows how to initiate a SIP registration session. It calls the 'register' method on the 'o_registration' object, which is assumed to be a pre-configured SIPml registration session.

```javascript
o_registration.register();
```

--------------------------------

### Configure SIP Stack Settings in JavaScript

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Configures the SIP stack with various parameters including authentication, network settings, and media capabilities. It uses JSON.stringify for bandwidth and video size, and iterates through custom SIP headers. This function is part of the SIPML5 library for managing SIP communication.

```javascript
tsk_utils_log_info("b_click2call_enabled=" + (b_click2call_enabled ? "yes" : "no"));
tsk_utils_log_info("b_early_ims=" + (b_early_ims ? "yes" : "no"));
tsk_utils_log_info("b_enable_media_stream_cache=" + (b_enable_media_stream_cache ? "yes" : "no"));
tsk_utils_log_info("o_bandwidth=" + JSON.stringify(o_bandwidth));
tsk_utils_log_info("o_video_size=" + JSON.stringify(o_video_size));

o_stack.set(
    tsip_stack.prototype.SetPassword(o_conf.password),
                     tsip_stack.prototype.SetDisplayName(o_conf.display_name),
                     tsip_stack.prototype.SetProxyOutBoundUrl(o_conf.outbound_proxy_url),
                     tsip_stack.prototype.SetRTCWebBreakerEnabled(b_rtcweb_breaker_enabled),
                     tsip_stack.prototype.SetClick2CallEnabled(b_click2call_enabled),
                     tsip_stack.prototype.SetSecureTransportEnabled((b_rtcweb_breaker_enabled || (window.location && window.location.protocol == "https:"))), // always use secure transport when RTCWebBreaker or https://
                     tsip_stack.prototype.SetEarlyIMSEnabled(b_early_ims), // should be 'true' unless you're using a real IMS network
                     tsip_stack.prototype.SetWebsocketServerUrl(o_conf.websocket_proxy_url),
                     tsip_stack.prototype.SetIceServers(o_conf.ice_servers),
                     tsip_stack.prototype.SetMediaStreamCacheEnabled(b_enable_media_stream_cache),
                     tsip_stack.prototype.SetBandwidth(o_bandwidth),
                     tsip_stack.prototype.SetVideoSize(o_video_size)
);

// add sip headers
if (o_conf.sip_headers) {
    o_conf.sip_headers.forEach(function (o_header) {
        if (o_header && !tsk_string_is_null_or_empty(o_header.name) && (!o_header.value || tsk_string_is_string(o_header.value))) {
            o_stack.set(
                tsip_stack.prototype.SetHeader(o_header.name, o_header.value)
            );
        }
    });
}

return 0;

```

--------------------------------

### Get Remote Party SIP URI

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Retrieves the SIP Uniform Resource Identifier (URI) of the remote party in a SIP session. This is useful for identifying the remote caller, potentially for matching against an address book. The function determines the URI based on whether the local session is initiating or receiving.

```javascript
SIPml.Session.prototype.getRemoteUri = function () {
    return (this.o_session.b_local ? this.o_session.o_uri_to : this.o_session.o_uri_from).toString();
}
```

--------------------------------

### Get SIP content object from event

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Retrieves the SIP content associated with the event as an object. Primarily used for accessing content from incoming SIP messages, particularly for 'i_new_message' events. Returns null if no message is available or content cannot be retrieved. Related methods include getContentString and getContentType.

```javascript
SIPml.Event.prototype.getContent = function () {
    var o_message = this.o_event ? this.o_event.get_message() : null;
    if (o_message) {
        return o_message.get_content();
    }
    return null;
}
```

--------------------------------

### SIPml.Stack Constructor and Validation - JavaScript

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

This code snippet shows the constructor for the SIPml.Stack object and the validation checks for the configuration parameters. It ensures that required fields like realm, IMPI, and IMPU are valid.

```JavaScript
SIPml.Stack = function (o_conf) {
    SIPml.init();
    SIPml.EventTarget.call(this);
    /*
    members:
    - o_stack {tsip_stack}
    */

    if (!o_conf) {
        throw new Error("ERR_INVALID_PARAMETER_VALUE: null configuration value");
    }
    if (tsk_string_is_null_or_empty(o_conf.realm)) {
        throw new Error("ERR_INVALID_PARAMETER_VALUE: '" + o_conf.realm + "' is not valid as realm value");
    }
    if (tsk_string_is_null_or_empty(o_conf.impi)) {
        throw new Error("ERR_INVALID_PARAMETER_VALUE: '" + o_conf.impi + "' is not valid as impi value");
    }
    if (tsk_string_is_null_or_empty(o_conf.impu)) {
        throw new Error("ERR_INVALID_PARAMETER_VALUE: '" + o_conf.impu + "' is not valid as impu value");
    }
    // check IMPU validity
    var o_impu = tsip_uri.prototype.Parse(o_conf.impu);
    if (!o_impu || !o_impu.s_user_name || !o_impu.s_host) {
        throw new Error("ERR_INVALID_PARAMETER_VALUE: '" + o_conf.impu + "' is not valid as SIP Uri");
    }

    var i_port;
    var s_proxy;

    if (!SIPml.isWebSocketSupported()) {
```

--------------------------------

### Get SIP content as string from event

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Retrieves the SIP content associated with the event as a string representation. Used for accessing the string content of incoming SIP messages, particularly for 'i_new_message' events. Returns null if no message is available. Related methods include getContent and getContentType for handling different content representations.

```javascript
SIPml.Event.prototype.getContentString = function () {
    var o_message = this.o_event ? this.o_event.get_message() : null;
    if (o_message) {
        return o_message.get_content_as_string();
    }
    return null;
}
```

--------------------------------

### Check webrtc4all Plugin Support (JavaScript)

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Checks if the webrtc4all plugin is supported. Requires the SIPml engine to be initialized. Returns true if supported; otherwise, false.

```javascript
SIPml.isWebRtc4AllSupported = function () {
    if (!SIPml.isInitialized()) {
        throw new Error("ERR_NOT_INITIALIZED: Engine not initialized yet. Please call 'SIPml.init()' first");
    }
    return SIPml.b_webrtc4all_supported;
}
```

--------------------------------

### Get SIP response code from event

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Retrieves the SIP response code from the event's wrapped session object. Returns the numeric response code for response messages (e.g. 404 for Not Found) or -1 if no valid response message is available. Useful for handling different SIP response scenarios programmatically.

```javascript
SIPml.Event.prototype.getSipResponseCode = function () {
    var o_message = this.o_event ? this.o_event.get_message() : null;
    if (o_message && o_message.is_response()) {
        return o_message.get_response_code();
    }
    return -1;
}
```

--------------------------------

### Subscribe to presence status using SIPml Session (JavaScript)

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

Creates a SIP SUBSCRIBE session for presence status. Demonstrates how to instantiate the session via stack.newSession with configuration options (expires, headers, capabilities) and defines the Subscribe class extending SIPml.Session.

```JavaScript
// Example usage to create a subscribe session
var session = stack.newSession('subscribe', {
    expires: 200,
    events_listener: { events: '*', listener: function(e){} },
    sip_headers: [
        { name: 'Event', value: 'presence' },
        { name: 'Accept', value: 'application/pidf+xml' }
    ],
    sip_caps: [
        { name: '+g.oma.sip-im', value: null },
        { name: '+audio', value: null },
        { name: 'language', value: '\"en,fr\"' }
    ]
});

// Subscribe session constructor
SIPml.Session.Subscribe = function (o_session, o_conf) {
    SIPml.Session.call(this, o_session, o_conf);
};

SIPml.Session.Subscribe.prototype = Object.create(SIPml.Session.prototype);
```

--------------------------------

### Configure SIPml5 Stack in JavaScript

Source: https://www.doubango.org/sipml5/docgen/symbols/src/SIPml

This JavaScript code demonstrates how to update the configuration of a SIPml5 stack. It validates various configuration parameters like realm, IMPI, IMPU, and SIP headers, throwing errors for invalid types. It also shows how to set event listeners and enables/disables features like RTCWEB breaker and click-to-call.

```javascript
SIPml.Stack.prototype.setConfiguration = function (o_conf) {
    if (o_conf.realm && !tsk_string_is_string(o_conf.realm)) {
        throw new Error("ERR_INVALID_PARAMETER_TYPE: '" + typeof o_conf.realm + "' not a valid type for realm. String is expected");
    }
    if (o_conf.impi && !tsk_string_is_string(o_conf.impi)) {
        throw new Error("ERR_INVALID_PARAMETER_TYPE: '" + typeof o_conf.impi + "' not a valid type for impi. String is expected");
    }
    if (o_conf.impu && !tsk_string_is_string(o_conf.impu)) {
        throw new Error("ERR_INVALID_PARAMETER_TYPE: '" + typeof o_conf.impu + "' not a valid type for impu. String is expected");
    }
    if (o_conf.password && !tsk_string_is_string(o_conf.password)) {
        throw new Error("ERR_INVALID_PARAMETER_TYPE: '" + typeof o_conf.password + "' not a valid type for password. String is expected");
    }
    if (o_conf.display_name && !tsk_string_is_string(o_conf.display_name)) {
        throw new Error("ERR_INVALID_PARAMETER_TYPE: '" + typeof o_conf.display_name + "' not a valid type for display_name. String is expected");
    }
    if (o_conf.websocket_proxy_url && !tsk_string_is_string(o_conf.websocket_proxy_url)) {
        throw new Error("ERR_INVALID_PARAMETER_TYPE: '" + typeof o_conf.websocket_proxy_url + "' not a valid type for websocket_proxy_url. String is expected");
    }
    if (o_conf.outbound_proxy_url && !tsk_string_is_string(o_conf.outbound_proxy_url)) {
        throw new Error("ERR_INVALID_PARAMETER_TYPE: '" + typeof o_conf.outbound_proxy_url + "' not a valid type for outbound_proxy_url. String is expected");
    }
    if (o_conf.sip_headers && typeof o_conf.sip_headers != "Array" && !(o_conf.sip_headers instanceof Array)) {
        throw new Error("ERR_INVALID_PARAMETER_TYPE: '" + typeof o_conf.sip_headers + "' not a valid type for sip_headers. Array is expected");
    }

    // event-listener: must be first to be defined as other configs could raise events
    if (o_conf.events_listener) {
        this.addEventListener(o_conf.events_listener.events, o_conf.events_listener.listener);
    }

    var b_rtcweb_breaker_enabled = !!o_conf.enable_rtcweb_breaker;
    var b_click2call_enabled = !!o_conf.enable_click2call;
    var b_early_ims = (o_conf.enable_early_ims == undefined) ? true : !!o_conf.enable_early_ims; // default value is true
    var b_enable_media_stream_cache = !!o_conf.enable_media_stream_cache;
    var o_bandwidth = o_conf.bandwidth ? o_conf.bandwidth : { audio: undefined, video: undefined };
    var o_video_size = o_conf.video_size ? o_conf.video_size : { minWidth: undefined, minHeight: undefined, maxWidth: undefined, maxHeight: undefined };
    var o_stack = this.o_stack;
    tsk_utils_log_info("s_websocket_server_url=" + (o_conf.websocket_proxy_url || "(null)"));
    tsk_utils_log_info("s_sip_outboundproxy_url=" + (o_conf.outbound_proxy_url || "(null)"));
    tsk_utils_log_info("b_rtcweb_breaker_enabled=" + (b_rtcweb_breaker_enabled ? "yes" : "no"));
```
Tokens:
Raw