B2B_ENTITIES

Anca-Maria Vamanu

   OpenSIPS

Edited by

Anca-Maria Vamanu

   Copyright © 2009 Anca-Maria
   Vamanu
   Revision History
   Revision $Revision: $ $Date: $
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSIPS Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. server_address (str)
              1.3.2. server_hsize (int)
              1.3.3. client_hsize (int)
              1.3.4. script_req_route (str)
              1.3.5. script_reply_route (str)
              1.3.6. Exported Functions

   2. Developer Guide

        2.1. b2b_load_api(b2b_api_t* api)
        2.2. server_new
        2.3. client_new
        2.4. send_request
        2.5. send_reply

   List of Examples

   1.1. Set server_address parameter
   1.2. Set server_hsize parameter
   1.3. Set client_hsize parameter
   1.4. Set script_req_route parameter
   1.5. Set script_repl_route parameter
   2.1. b2b_api_t structure

Chapter 1. Admin Guide

1.1. Overview

   The B2BUA implementation in OpenSIPS is separated in two
   layers:
     * a lower one(coded in this module)- which implements the
       basic functions of a UAS and UAC
     * a upper one - which represents the logic engine of B2BUA,
       responsible of actually implementing the B2BUA services
       using the functions offered by the low level.

   This module stores records corresponding to the dialogs in
   which the B2BUA is involved. It exports an API to be called
   from other modules which offers functions for creating a new
   dialog record, for sending requests or replies in one dialog
   and will also notify the upper level module when a request or
   reply is received inside one stored dialog. The records are
   separated in two types: b2b server entities and b2b client
   entities depending on the mode they are created. An entity
   created for a received initial message will be a server entity,
   while a entity that will send an initial request(create a new
   dialog) will be a b2b client entity. The name corresponds to
   the behavior in the first transaction - if UAS - server entity
   and if UAC - client entity. This module does not implement a
   B2BUA alone, but needs a B2B logic implementing module.

1.2. Dependencies

1.2.1. OpenSIPS Modules

     * tm

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS with this module loaded:
     * none

1.3. Exported Parameters

1.3.1. server_address (str)

   The IP address of the machine that will be used as Contact in
   the sent messages.

   Example 1.1. Set server_address parameter
...
modparam("b2b_entities", "server_address", "sip:sa@10.10.10.10:5060")
...

1.3.2. server_hsize (int)

   The size of the hash table that stores the b2b server entities.
   It is the 2 logarithmic value of the real size.

   Default value is "9" (512 records).

   Example 1.2. Set server_hsize parameter
...
modparam("b2b_entities", "server_hsize", 10)
...

1.3.3. client_hsize (int)

   The size of the hash table that stores the b2b client entities.
   It is the 2 logarithmic value of the real size.

   Default value is "9" (512 records).

   Example 1.3. Set client_hsize parameter
...
modparam("b2b_entities", "client_hsize", 10)
...

1.3.4. script_req_route (str)

   The name of the b2b script route that will be called when B2B
   requests are received.

   Example 1.4. Set script_req_route parameter
...
modparam("b2b_entities", "script_req_route", "b2b_request")
...

1.3.5. script_reply_route (str)

   The name of the b2b script route that will be called when B2B
   replies are received.

   Example 1.5. Set script_repl_route parameter
...
modparam("b2b_entities", "script_reply_route", "b2b_reply")
...

1.3.6. Exported Functions

   The module does not export functions to be used in
   configuration script.

Chapter 2. Developer Guide

   The module provides an API that can be used from other OpenSIPS
   modules. The API offers the functions for creating and handing
   dialogs. A dialog can be created on a receipt initial message,
   and this will correspond to a b2b server entity, or initiated
   by the server and in this case a client entity will be created
   in b2b_entities module.

2.1.  b2b_load_api(b2b_api_t* api)

   This function binds the b2b_entities modules and fills the
   structure the exported functions that will be described in
   detail.

   Example 2.1. b2b_api_t structure
...
typedef struct b2b_api {
        b2b_server_new_t          server_new;
        b2b_client_new_t          client_new;

        b2b_send_request_t        send_request;
        b2b_send_reply_t          send_reply;
}presence_api_t;
...

2.2.  server_new

   Field type:
...
typedef str* (*b2b_server_new_t) (struct sip_msg* ,b2b_notify_t , void*
param);
...

   This function asks the b2b_entities modules to create a new
   server entity record. The internal processing actually extracts
   the dialog information from the message and constructs a record
   that will be stored in a hash table. The second parameters is a
   pointer to a function that the b2b_entities module will call
   when a event will come for that dialog (a request or reply).
   The third parameter is a pointer to a value that will be stored
   and given as a parameter when the notify function will be
   called(it has to be allocated in shared memory).

   The return value is an identifier for the record that will be
   mentioned when calling other functions that represent actions
   in the dialog(send request, send reply).

   The notify function has the following prototype:
...
typedef int (*b2b_notify_t)(struct sip_msg* msg, str* id, int type, void
* param);
...

   This function is called when a request or reply is received for
   a dialog handled by b2b_entities. The first parameter is the
   message, the second is the identifier for the dialog, the third
   is a flag that says which is the type of the message(it has two
   possible values - B2B_REQUEST and B2B_REPLY). The last
   parameter is the parameter by the upper module when the entity
   was created.

2.3.  client_new

   Field type:
...
typedef str* (*b2b_client_new_t) (str* method, str* to_uri, str* from_ur
i,
                str* extra_headers, str* body, b2b_notify_t b2b_cback, v
oid* param);
...

   This function asks the b2b_entities modules to create a new
   client entity record and also create a new dialog by sending an
   initial message. The parameters are all the values needed for
   the initial request to which the notify function and parameter
   are added.

   The return value is an identifier for the record that will be
   mentioned when calling other functions that represent actions
   in the dialog(send request, send reply).

2.4.  send_request

   Field type:
...
typedef int (*b2b_send_request_t)(enum b2b_entity_type et, str* b2b_key,
 str* method,
                str* extra_headers, str* body)
...

   This function asks the b2b_entities modules to send a request
   inside a b2b dialog identified by b2b_key. The first parameter
   is the entity type and can have two values: B2B_SERVER and
   B2B_CLIENT. The second is the identifier returned by the create
   function(server_new or client_new) and the next are the
   informations needed for the new request: method, extra_headers,
   body.

   The return value is 0 for success and a negative value for
   error.

2.5.  send_reply

   Field type:
...
typedef int (*b2b_send_reply_t)(enum b2b_entity_type et, str* b2b_key, i
nt code, str* text,
                str* body, str* extra_headers);
...

   This function asks the b2b_entities modules to send a reply
   inside a b2b dialog identified by b2b_key. The first parameter
   is the entity type and can have two values: B2B_SERVER and
   B2B_CLIENT. The second is the identifier returned by the create
   function(server_new or client_new) and the next are the
   informations needed for the new reply: code, text, body,
   extra_headers.

   The return value is 0 for success and a negative value for
   error.
