Documentation -> Development Manual 3.3 -> BIN Interface API

This page has been visited 486 times. (:title OpenSIPS Development - BIN Interface API:)

(:allVersions Development-Manual-API-BIN 3.3:)

(:toc-float Table of Content:)

The Binary Internal Interface is an OpenSIPS core interface which offers an efficient way for communication between individual OpenSIPS instances.
This is especially useful in scenarios where realtime data (such as dialogs) cannot be simply stored in a database anymore, because failover would require entire minutes to complete. This issue can be solved with the new internal binary interface by replicating all the events related to the runtime data (creation / updating / deletion) to a backup OpenSIPS instance.
The BIN interface functionality is exported by the bin_interface.h file.
Using the interface has two steps :

• creating and sending the new event from the Active OpenSIPS server
• receiving and processing the event in the Backup OpenSIPS server

For creating and sending a new event, the following methods are to be used : (:source lang=C -link -getcode :) /**

 * bin_init - begins the construction of a new binary packet (header part):
 *
 * +-------------------+------------------------------------------------------+
 * |  8-byte HEADER    |                 BODY                max 65535 bytes  |
 * +-------------------+------------------------------------------------------+
 * | PK_MARKER |  CRC  | LEN | MOD_NAME | CMD | LEN | FIELD | LEN | FIELD |...|
 * +-------------------+------------------------------------------------------+
 *
 * @param: { LEN, MOD_NAME } + CMD
 */

int bin_init(str *mod_name, int cmd_type)

/*

 * copies the given string at the 'cpos' position in the buffer
 * allows null strings (NULL content or NULL param)
 *
 * @return: 0 on success
 */

int bin_push_str(const str *info)

/*

 * adds a new integer value at the 'cpos' position in the buffer
 *
 * @return: 0 on success
 */

int bin_push_int(int info)

/**

 * bin_send - computes the checksum of the current packet and then
 * sends the packet over UDP to the @dest destination
 *
 * @return: number of bytes sent, or -1 on error
 */

int bin_send(union sockaddr_union *dest) (:sourceend:)
On the receiving end, the developer must first register a callback that will be trigger when receiving special types of BIN message, by using the following :

(:source lang=C -link -getcode :) /**

 * bin_register_cb - registers a module handler for specific packets
 * @mod_name: used to classify the incoming packets
 * @cb:       the handler function, called once for each matched packet
 *
 * @return:   0 on success
 */

int bin_register_cb(char *mod_name, void (*cb)(int)) (:sourceend:)
The callback will only be triggered for the mod_name class of BIN packages, and also the callback will receive the packet type as well, in order to be able to differentiate between multiple types of events ( eg. create, update, delete, etc ).
Afterwards, you should use the pop methods for extracting the contents of the package : (:source lang=C -link -getcode :) /*

 * pops an str from the current position in the buffer
 * @info:   pointer to store the result
 *
 * @return: 0 on success
 *
 * Note: The pointer returned in @info str is only valid for the duration of
 *       the callback. Don't forget to copy the info into a safe buffer!
 */

int bin_pop_str(str *info)

/*

 * pops an integer value from the current position in the buffer
 * @info:   pointer to store the result
 *
 * @return: 0 on success
 */

int bin_pop_int(void *info) (:sourceend:)
See the main page dedicated to the Binary Interface on how to then configure OpenSIPS listeners for the binary packages.