PbxApi
This document describes the PbxApi object in the JavaScript environment for app serivices.
PBX APIs are used on incoming AppWebsocket connections from app objects on the PBX to the app service. You can use any PBX API in your app service that is activated at the app object in the PBX.
Table of content
PbxApi
Constructor for creating a PBX API object.
Parameters
| string api | The identifier for the API. |
var replicationApi = new PbxApi("PbxTableUsers");
onconnected
Registers a callback function that is invoked when a new AppWebsocket from a PBX is connected that supports the API.
Parameters
| function callback(PbxApiConnection conn) | The conn parameter passed with the callback can be used to send and receive API messages on the connection. |
Return value
| PbxApi | A reference to the object itself. Useful for method chaining. |
new PbxApi("PbxTableUsers").onconnected(function(conn) {
log("new connection with PbxTableUsers support");
});
api
The ID of the API.
domain
The domain of the connected PBX.
pbx
The name of the connected PBX.
pbxDns
The DNS name of the connected PBX.
version
The version of the PBX.
build
The build number of the PBX.
info
A string containing the info of the app object the AppWebsocket connection was established from. It contains a JSON structure that includes additional info like the app object name or number of service licenses assigned to this app object.
onmessage
Registers a callback function that is invoked when receiving an API message
Parameters
| function callback(string msg) | A string containg a JSON structure. Must be parsed using JSON.parse. |
Return value
new PbxApi("PbxApi").onconnected(function(conn) {
conn.send(JSON.stringify({ api: "PbxApi", mt: "SubscribePresence", sip: "johndoe" }));
conn.onmessage(function(msg) {
var obj = JSON.parse(msg);
if (obj.mt == "SubscribePresenceResult") {
conn.send(JSON.stringify({ api: "PbxApi", mt: "UnsubscribePresence", src: obj.src }));
}
});
});
onclose
Registers a callback function that is invoked when the AppWebsocket connection was closed by the PBX.
Parameters
| function callback() | The callback that shall be invoked when the connection was closed. |
Return value
new PbxApi("PbxTableusers").onconnected(function(conn) {
log("connected");
conn.onclose(function() {
log("closed");
});
});
send
Sends a JSON message.
Parameters
| string message | A string (max. length 65535) containing a JSON structure that represents the API message. |
Return value
conn.send(JSON.stringify({ api: "PbxApi", mt: "SubscribePresence", sip: "john.doe" }));
setFlowControl
Tells the library that it wants to use flow control. That means that after receiving the onmessage callback, the library should deliver no more messages until the application has called messageComplete
Parameters
| bool on | true if flow control shall be used. false if flow control should not be used. |
Return value
new PbxApi("PbxApi").onconnected(function(conn) {
conn.setFlowControl(true)
.onmessage(function(msg) {
var obj = JSON.parse(msg);
if (obj.mt == "SubscribePresenceResult") {
// do something
}
conn.messageComplete();
});
});
messageComplete
Tells the library that the application is ready to receive the next message using the onmessage callback.
Return value
new PbxApi("PbxApi").onconnected(function(conn) {
conn.setFlowControl(true)
.onmessage(function(msg) {
var obj = JSON.parse(msg);
if (obj.mt == "SubscribePresenceResult") {
// do something
}
conn.messageComplete();
});
});
encrypt
Encrypts a string using the shared secret of the connection and a random seed.
Parameters
| string seed | A seed value that shall be unique for each call. The seed is needed by the remote party for decryption. |
| string data | The string to be encrypted. |
Return value
| string | The encrypted string. |
var seed = "some seed";
var secret = "some secret text";
var encryptedText = conn.encrypt(seed, secret);
conn.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 seed | The seed needs to be given by the remote party for decryption. |
| string data | The encrypted string. |
Return value
| string | The decrypted string. |
conn.onmessage(function(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 seed | A seed value that shall be unique for each call. |
| string data | The string to be hashed. |
Return value
| string | The 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 }));
create
Creates a new PbxApiConnection object, that uses the same underlying websocket connection, but with a different target API.
This mechanism can be used along with the PbxImpersonation API.
Parameters
| string targetApi | The target API value, as returned with the CreateApiResult message of the PbxImpersonationApi |
Return value
new PbxApi("PbxImpersonation").onconnected(function(conn) {
conn.send(JSON.stringify({ api: "PbxImpersonation", mt: "CreateApi", sip: "johndoe", target: "PbxApi" }));
conn.onmessage(function(msg) {
var obj = JSON.parse(msg);
if (obj.mt == "CreateApiResult") {
// create new PbxApiConnection object with the returned target API name
var targetApi = obj.target;
var pbxApiConn = conn.create(targetApi);
pbxApiConn.onmessage(function(msg) { });
pbxApiConn.send(JSON.stringify({ api: targetApi, mt: "SubscribeProfile", sip: "johndoe" }));
}
});
});
close
Closes the PbxApiConnection object. This should be done if the application is not or no longer interested in using
the related PbxApi on that connection.
Please note that the underlying websocket connection is not affected and stays connected.
Return value
new PbxApi("PbxApi").onconnected(function(conn) {
if (pbx != "master") conn.close();
});