AppWebsocketClient

This document describes the AppWebsocketClient available in the JavaScript environment for app serivices.

Table of content

Object AppWebsocketClient
Functions connect

Object AppWebsocketClientConnection
Functions onauth
onopen
onclose
onmessage
auth
send
close
setFlowControl
messageComplete
encrypt
decrypt
hash

Examples Connecting to another app service using the Services API of the pbx

AppWebsocketClient

connect
Creates a AppWebsocketClientConnection object. The actual connection is started asynchronously. So synchronous function calls on that object are handled before the connection is established.

Parameters

string uriAn absolute conn: or wss: URI.
string passwordThe password for authentication. Set to null or leave emtpy if you use the asynchronous authentication flow using onauth and auth
string appThe name of the app you like to login at.
string domainThe domain of the logged-in user. Optional. Set to null or leave empty if you use the asynchronous authentication flow using onauth and auth
string sipThe SIP URI of the logged-in user. Optional. Set to null or leave empty if you use the asynchronous authentication flow using onauth and auth
string guidThe GUID of the logged-in user. Optional. Set to null or leave empty if you use the asynchronous authentication flow using onauth and auth
string dnThe display name of the logged-in user. Optional. Set to null or leave empty if you use the asynchronous authentication flow using onauth and auth

Return value

AppWebsocketClientConnectionAn object representing the appwebsocket connection.
var appwebsocket = AppWebsocketClient.connect("wss://pbx.example.com/PBX0/APPS/websocket", "password", "appname", "example.com", "john.doe", "guid", "John Doe");
var appwebsocket = AppWebsocketClient.connect("wss://pbx.example.com/PBX0/APPS/websocket", null, "appname");
appwebsocket.onauth(function(conn, app, challenge) { 
    // get login parameters asynchronously (e.g. using Services API) and then call the auth function
    conn.auth(...);
});

AppWebsocketClientConnection

onauth
Sets a callback function that is invoked when the server sent the challenge and is now waiting for the actual login parameters. Optional. Use, if your app doesn't know the password for the server, but uses for example the Services API to get the login parameters from the PBX. If the callback is set the library will pause the authentication process until the login parameters are given using the auth function.

Parameters

function callback(AppWebsocketClientConnection connection, string app, string challenge)A callback that processes the servers challenge.

Return value

AppWebsocketClientConnectionA reference to the object itself. Useful for method chaining.
var appwebsocket = AppWebsocketClient.connect("wss://pbx.example.com/PBX0/APPS/websocket", null, "appname");
appwebsocket.onauth(function(conn, app, challenge) {
    // get login parameters asynchronously (e.g. using Services API) and then call the auth function
    conn.auth(...);
});
onopen
Sets a callback function that is invoked when the connection is established. Optional.

Parameters

function callback(AppWebsocketClientConnection connection)A callback that will be called when the connection is established.

Return value

AppWebsocketClientConnectionA reference to the object itself. Useful for method chaining.
appwebsocket.onopen(function(conn) {
    log("connection is up");
});
onclose
Sets a callback function that is invoked when the connection is closed. Optional.

Parameters

function callback(AppWebsocketClientConnection connection)A callback that will be called when the connection is closed. After the callback the connection object is gone and can not be used anymore.

Return value

AppWebsocketClientConnectionA reference to the object itself. Useful for method chaining.
appwebsocket.onclose(function(conn) {
    log("connection closed");
});
onmessage
Sets a callback function that is invoked when a appwebsocket message is received. Optional.

Parameters

function callback(AppWebsocketClientConnection connection, message)A callback that will be called when the connection is closed. The message attribute represents the text received with the message.

Return value

AppWebsocketClientConnectionA reference to the object itself. Useful for method chaining.
appwebsocket.onmessage(function(conn, msg) {
    var obj = JSON.parse(msg);
    if (obj.mt == "SomeMessage") {
        // ...
    }
});
auth
Continues the authentication with the given parameters. This function should be only called if the onauth callback has been used for asynchronous authentication.

Parameters

string domainThe domain of the logged-in user.
string sipThe SIP URI of the logged-in user.
string guidThe GUID of the logged-in user.
string dnThe display name of the logged-in user.
string pbxObjThe name of the PBX object representing the remote endpoint.
string appThe app name of the remote endpoint.
string infoAdditional info encoded as a JSON string.
string digestThe login digest.
string keyThe session key to be used.

Return value

AppWebsocketClientConnectionA reference to the object itself. Useful for method chaining.
var appwebsocket = AppWebsocketClient.connect("wss://pbx.example.com/PBX0/APPS/websocket", null, "appname");
appwebsocket.onauth(function(conn, app, challenge) {
    // get login parameters asynchronously (e.g. using Services API) and then call the auth function
    conn.auth(...);
});
send
Sends a appwebsocket text message.

Parameters

string messageThe text message to be sent.

Return value

AppWebsocketClientConnectionA reference to the object itself. Useful for method chaining.
appwebsocket.send(JSON.stringify({ mt: "SomeMessage" }));
setFlowControl
Enables flow control for the connection. That means that after receiving a message with the onmessage callback, the AppWebsocketClientConnection waits for the application to call messageComplete before receiving more messages. Optional.

Parameters

bool enabledTrue if flow controll shall be used.

Return value

AppWebsocketClientConnectionA reference to the object itself. Useful for method chaining.
appwebsocket.setFlowControl(true);

appwebsocket.onmessage(function(conn, msg) {
    var obj = JSON.parse(msg);
    if (obj.mt == "SomeMessage") {
        // ...
    }
    conn.messageComplete();
});
messageComplete
Tells the library to receive the next appwebsocket message. See setFlowControl for details.

Return value

AppWebsocketClientConnectionA reference to the object itself. Useful for method chaining.
appwebsocket.setFlowControl(true);

appwebsocket.onmessage(function(conn, msg) {
    var obj = JSON.parse(msg);
    if (obj.mt == "SomeMessage") {
        // ...
    }
    conn.messageComplete();
});
encrypt
Encrypts a string using the shared secret of the connection and a random seed.

Parameters

string seedA seed value that shall be unique for each call. The seed is needed by the remote party for decryption.
string dataThe string to be encrypted.

Return value

stringThe encrypted string.
var seed = "some seed";
var secret = "some secret text";
var encryptedText = conn.encrypt(seed, secret);
appwebsocket.send(JSON.stringify({ mt: "SomeMessage", seed: seed, encryptedText: encryptedText }));
decrypt
Decrypts a string using the shared secret of the connection and a random seed.

Parameters

string seedThe seed needs to be given by the remote party for decryption.
string dataThe encrypted string.

Return value

stringThe decrypted string.
appwebsocket.onmessage(function(conn, msg) {
    var obj = JSON.parse(msg);
    if (obj.mt == "SomeMessage") {
        var secret = conn.decrypt(obj.seed, obj.encryptedText);
    }
});
hash
Calculates a hash value using the shared secret of the connection and a random seed.

Parameters

string seedA seed value that shall be unique for each call.
string dataThe string to be hashed.

Return value

stringThe calculated hash value.
var seed = "some seed";
var text = "some secret text";
var hash = conn.hash(seed, secret);
conn.send(JSON.stringify({ mt: "SomeMessage", text: text, seed: seed, hash, hash }));

Example: Connecting to another app service using the Services API of the pbx

This examples demonstrates how to connect to another app service. The password for the app service is unknown so we make use of the Services API of the PBX to get the needed credentials. For that the app object needs some special settings in the PBX.

Code example


// track websocket connection from the PBX supporting the Services API

var servicesApi = null;
new PbxApi("Services").onconnected(function(conn) {
    servicesApi = conn;
    conn.onclose(function() {
        servicesApi = null;
    });
});

// connect to other app service

function connectToService(uri, app) {
    var appwebsocket = AppWebsocketClient.connect(uri, null, app);

    // asynchonous authentication using Services API
    appwebsocket.onauth(function(conn, app, challenge) {
        if (!servicesApi) {
            log("no connection to PBX");
            appwebsocket.close();
        }
        else {
            servicesApi.send(JSON.stringify({api: "Services", mt:"GetServiceLogin", challenge: challenge, app: app}));
            servicesApi.onmessage(function(message) {
                var msg = JSON.parse(message);
                if (msg.mt == "GetServiceLoginResult") {
                    if (msg.error) {
                        log("login failed");
                        appwebsocket.close();
                    }
                    else {
                        // pass received login parameters to library
                        var key = servicesApi.decrypt(msg.salt, msg.key);
                        var info = JSON.stringify(msg.info);
                        appwebsocket.auth(msg.domain, msg.sip, msg.guid, msg.dn, msg.pbxObj, msg.app, info, msg.digest, key);
                    }
                }
            });
        }
    });

    appwebsocket.onopen(function(conn) {
        // connection is up
    });

    appwebsocket.onmessage(function (conn, msg) {
        // process incoming messages
    });

    appwebsocket.onclose(function(conn) {
        // connection is closed
    });
}