High Availability Switch Module

Easy to use application programming interface

SECDATA

API

api

HAsm API communications take place in plain text (optionally encrypted), and the connection can exist over a variety of media including TCP/IP, serial (RS-232 or RS-485), CAN bus, and more. Messages are comprised of key-value pairs, with each message comprised of two or more key-value pairs followed by a blank line. Each message must contain a unique identifier, a message type, and parameters appropriate for the type. Three types of messages are support:

Command: A request from one side to the other side. The request instructs the other side to take some action, or provide information.
Response: Each command must be followed by a response. At a minimum it acknowledges the command, but may also contain data results from the command. If a response is not received from the other side in a after a predetermine amount of time, the client API will return a time-out response to the local client.
Notification: A notice from one side to the other side that a state has changed, and event has occurred, or some signal has been received.

Customer applications can communicate with HAsm as easily as reading/writing a file (using the domain socket interface), or reading from/writing to a TCP port (using the TCP/IP interface). The customer can use any development language (eg: C, Python, JavaScript, C++, Perl, etc.) to communicate with the HAsm API. Telium also offers a precompiled client API client (Linux .so or .a file, or Windows .dll) which handles all aspects of communications. The precompiled client API is required if using API encryption, but can also can accelerate product development.

Command Response Example

The image to the right contains two messages, a command and its associated response. Each message is comprised of key-value pairs in plane text format, followed by a blank line to indicate the end of the message. The example command instructs the other side (in this case HAsm) to disconnect a call in progress. The mandatory parameter is the call ID (which may have been received earlier by way of a command/response or a notification).

Below the command is the associated response message. Notice that the response message contains the same ID as the command, allowing the client to reconcile responses with commands. As many commands can be sent sequentially, there is no guaranteed order of responses, so ID’s must be considered. In this case the response indicates success (0 result code) with further detail available in the next parameter (result message).

These commands and responses are examples only, and might not exist in every customer deployment. Telium will include only those commands/responses necessary to deliver the functionality specified by the customer. All superfluous commands/responses are removed.

Notification Example

The image to the right contains two messages, both notifications. The messages are comprised of key-value pairs in plane text format, followed by a blank line to indicate the end of the message. The first example notifies the other side (in this case the customer app) that a user agent has registered. The mandatory parameters are the notice (what type of notification is this), the user agent identified, the user agent string, and the contact string for the UA. In this example these are the fields required by the customer (but many more informational fields are available). The second message notifies the other side (again the customer app) that the local node is promoting to active as it has lost contact with its peer. The mandatory parameters are the reason code (129) and reason message.

These notifications are examples only, and might not exist in every customer deployment. Telium will include only those notifications necessary to deliver the functionality specified by the customer. All superfluous notifications and fields are removed.