B2B_LOGIC

Anca-Maria Vamanu

   OpenSIPS

Edited by

Anca-Maria Vamanu

Edited by

Ovidiu Sas

   Copyright © 2009 Anca-Maria
   Vamanu

   Copyright © 2010 VoIP Embedded, Inc.
   Revision History
   Revision $Revision: 8137 $ $Date: 2013-01-29 14:35:11 +0200
                              (Tue, 29 Jan 2013) $
     __________________________________________________________

   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. hash_size (int)
              1.3.2. script_scenario (str)
              1.3.3. extern_scenario (str)
              1.3.4. cleanup_period (int)
              1.3.5. custom_headers_regexp (str)
              1.3.6. custom_headers (str)
              1.3.7. use_init_sdp (int)
              1.3.8. db_url (str)
              1.3.9. update_period (int)
              1.3.10. max_duration (int)
              1.3.11. b2bl_from_spec_param (string)
              1.3.12. server_address (str)
              1.3.13. init_callid_hdr (str)
              1.3.14. db_mode (int)
              1.3.15. db_table (str)
              1.3.16. b2bl_th_init_timeout (int)

        1.4. Exported Functions

              1.4.1. b2b_init_request
              1.4.2. b2b_bridge_request(b2bl_key,entity_no)

        1.5. Exported MI Functions

              1.5.1. b2b_trigger_scenario
              1.5.2. b2b_bridge
              1.5.3. b2b_list

   2. Developer Guide

        2.1. b2b_logic_bind(b2bl_api_t* api)
        2.2. init
        2.3. bridge
        2.4. bridge_extern
        2.5. bridge_2calls
        2.6. terminate_call
        2.7. set_state
        2.8. bridge_msg

   List of Examples

   1.1. Set server_hsize parameter
   1.2. Set script_scenario parameter
   1.3. Set script_scenario parameter
   1.4. Set cleanup_period parameter
   1.5. Set parameter
   1.6. Set parameter
   1.7. Set parameter
   1.8. Set db_url parameter
   1.9. Set update_period parameter
   1.10. Set max_duration parameter
   1.11. Set b2bl_from_spec_param parameter
   1.12. Set server_address parameter
   1.13. Set init_callid_hdr parameter
   1.14. Set db_mode parameter
   1.15. Set db_table parameter
   1.16. Set b2bl_th_init_timeout parameter
   1.17. b2b_init_request usage
   1.18. b2b_bridge_request usage
   2.1. b2bl_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 b2b_entities module)- which implements
       the basic functions of a UAS and UAC
     * an 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 is a B2BUA upper level implementation that can be
   used with b2b_entities module to have B2BUA that can be
   configured to provide some PBX services. The B2B services are
   coded in an XML scenario document. The b2b_logic module
   examines this document and uses the functions provided by the
   b2b_entities module to achieve the actions specified in the
   document and enable the service.

   A scenario can be instantiated in two ways:
     * from the script - at the receipt of a initial message
     * with a extern command (MI) command - the server will
       connect two end points in a session(Third Party Call
       Control).

1.2. Dependencies

1.2.1. OpenSIPS Modules

     * b2b_entities, a db module

1.2.2. External Libraries or Applications

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

1.3. Exported Parameters

1.3.1. hash_size (int)

   The size of the hash table that stores the scenario
   instatiation entities.

   Default value is “9” (512 records).

   Example 1.1. Set server_hsize parameter
...
modparam("b2b_logic", "hash_size", 10)
...

1.3.2. script_scenario (str)

   This parameter should be set with the path of a document that
   contains a scenario that can be instantiated from the script at
   the receipt of an initial message.

   This parameter can be set more than once.

   Example 1.2. Set script_scenario parameter
...
modparam("b2b_logic", "script_scenario", "/opt/opensips/scripts/b2
b_prepaid.xml")
...

1.3.3. extern_scenario (str)

   This parameter should be set with the path of a document that
   contains a scenario that can be instantiated with an MI
   command.

   This parameter can be set more than once.

   Example 1.3. Set script_scenario parameter
...
modparam("b2b_logic", "extern_scenario", "/opt/opensips/scripts/b2
b_marketing.xml")
...

1.3.4. cleanup_period (int)

   The time interval at which to search for an hanged b2b context.
   A scenario is considered expired if the duration of a session
   exceeds the lifetime specified in the scenario. At that moment,
   BYE is sent in all the dialogs from that context and the
   context is deleted.

   Default value is “100”.

   Example 1.4. Set cleanup_period parameter
...
modparam("b2b_logic", "cleanup_period", 60)
...

1.3.5. custom_headers_regexp (str)

   Regexp to search SIP header by names that should be passed from
   the dialog of one side to the other side. There are a number of
   headers that are passed by default. They are:
     * Content-Type
     * Supported
     * Allow
     * Proxy-Require
     * Session-Expires
     * Min-SE
     * Require
     * RSeq

   If you wish some other headers to be passed also you should
   define them by setting this parameter.

   It can be in forms like "regexp", "/regexp/" and
   "/regexp/flags".

   Meaning of the flags is as follows:
     * i - Case insensitive search.
     * e - Use extended regexp.

   Default value is “NULL”.

   Example 1.5. Set parameter
...
modparam("b2b_logic", "custom_headers_regexp", "/^x-/i")
...

1.3.6. custom_headers (str)

   A list of SIP header names delimited by ';' that should be
   passed from the dialog of one side to the other side. There are
   a number of headers that are passed by default. They are:
     * Max-Forwards (it is decreased by 1)
     * Content-Type
     * Supported
     * Allow
     * Proxy-Require
     * Session-Expires
     * Min-SE
     * Require
     * RSeq

   If you wish some other headers to be passed also you should
   define them by setting this parameter.

   Default value is “NULL”.

   Example 1.6. Set parameter
...
modparam("b2b_logic", "custom_headers", "User-Agent;Date")
...

1.3.7. use_init_sdp (int)

   This parameter modifies the behaviour of the B2BUA when
   bridging and a provisional media uri is set. For playing media
   while the callee answers (that is connecting the caller to a
   media server), the bridging with the callee must start by
   sending an Invite to it. The correct way is to send an Invite
   without a body in this case, but it has been observed that not
   many gateways support this. So, the solution is to use the sdp
   received in the first Invite from the caller and put it as the
   body for this invite. By setting this parameter, this behavior
   is enabled. You can also set use_init_sdp per scenario and
   overwrite this global value.

   Default value is “0”.

   Example 1.7. Set parameter
...
modparam("b2b_logic", "use_init_sdp", 1)
...

1.3.8. db_url (str)

   Database URL.

   Example 1.8. Set db_url parameter
...
modparam("b2b_logic", "db_url", "mysql://opensips:opensipsrw@127.0.0.1/o
pensips")
...

1.3.9. update_period (int)

   The time interval at which to update the info in database.

   Default value is “100”.

   Example 1.9. Set update_period parameter
...
modparam("b2b_logic", "update_period", 60)
...

1.3.10. max_duration (int)

   The maximum duration of a call.

   Default value is “12 * 3600 (12 hours)”.

   If you set it to 0, there will be no limitation.

   Example 1.10. Set max_duration parameter
...
modparam("b2b_logic", "max_duration", 7200)
...

1.3.11. b2bl_from_spec_param (string)

   The name of the pseudo variable for storing the new “From”
   header. The PV must be set before calling “b2b_init_request”.

   Default value is “NULL” (disabled).

   Example 1.11. Set b2bl_from_spec_param parameter
...
modparam("b2b_logic", "b2bl_from_spec_param", "$var(b2bl_from)")
...
route{
        ...
        # setting the From header
        $var(b2bl_from) = "\"Call ID\" <sip:user@opensips.org>";
        ...
        b2b_init_request("top hiding");
        ...
}

1.3.12. server_address (str)

   The IP address of the machine that will be used as Contact in
   the generated messages. This is compulsory only when using
   external scenarios. For the script scenarios, if it is not set,
   it is constructed dynamically from the socket where the
   initiating request was received. This socket will be used to
   send all the requests, replies for that scenario instantiation.

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

1.3.13. init_callid_hdr (str)

   The module offers the possibility to insert the original callid
   in a header in the generated Invites. If you want this, set
   this parameter to the name of the header in which to insert the
   original callid.

   Example 1.13. Set init_callid_hdr parameter
...
modparam("b2b_logic", "init_callid_hdr", "Init-CallID")
...

1.3.14. db_mode (int)

   The B2B modules have support for the 3 type of database storage

     * NO DB STORAGE - set this parameter to 0
     * WRITE THROUGH (synchronous write in database) - set this
       parameter to 1
     * WRITE BACK (update in db from time to time) - set this
       parameter to 2

   Default value is “2” (WRITE BACK).

   Example 1.14. Set db_mode parameter
...
modparam("b2b_logic", "db_mode", 1)
...

1.3.15. db_table (str)

   Name of the database table to be used

   Default value is “b2b_logic”

   Example 1.15. Set db_table parameter
...
modparam("b2b_logic", "db_table", "some_table_name")
...

1.3.16. b2bl_th_init_timeout (int)

   Call setup timeout for topology hiding scenario.

   Default value is “60”

   Example 1.16. Set b2bl_th_init_timeout parameter
...
modparam("b2b_logic", "b2bl_th_init_timeout", 60)
...

1.4. Exported Functions

1.4.1.  b2b_init_request

   This is the function that must be called by the script writer
   on an initial INVITE for which a B2B scenario must be
   instantiated. It is up to the script writer to decide which are
   the criteria to decide for which messages certain scenarios
   must be instantiated.

   The first parameter is the identifier for the scenario and
   possible flags. This is defined in the XML document as an
   attribute of the root node or "top hiding" for internal
   topology hiding scenario. It can be passed as "scenario" or
   "scenario_name/flags".

   Meaning of the flags is as follows:
     * t[nn] - Call setup timeout for topology hiding scenario.
       Example: t300.
     * a - Transparent authentication. In this mode b2b passes
       your 401 or 407 authentication request to destination
       server.
     * p - Preserve To: header.

   Then it can take at most 4 other parameters that represent the
   parameters for the xml scenario. The expected number of
   parameters is also specified as an attribute in the root node
   of the XML scenario.

Note

   If you have a multi interface setup and want to chance the
   outbound interface, it is mandatory to use the
   "force_send_socket()" core function before passing control to
   b2b function. If you do not do it, the requests may be
   correctly routed, but the SIP pacakge may be invalid (as
   Contact, Via, etc).

   Example 1.17. b2b_init_request usage
...
if(is_method("INVITE") && !has_totag() && prepaid_user())
   b2b_init_request("prepaid", "sip:320@opensips.org:5070",
      "sip:321@opensips.org:5070"));
...

1.4.2.  b2b_bridge_request(b2bl_key,entity_no)

   This function will bridge an initial INVITE with one of the
   particapnts from an existing b2b dialog.

   Parameters:
     * b2bl_key - a pseudo-variable that contains the b2b_logic
       key
     * entity_no - a pseudo-variable that holds the entity of the
       particapnt to bridge.

   Example 1.18. b2b_bridge_request usage
...
modparam("b2b_logic", "b2bl_key_avp", "$avp(99)")
...
route(X)
{
   # handling b2b calls here
   ...
   b2b_init_request("top hiding");
   xlog("L_INFO","[$mi] got b2bl_key='$avp(99)'\n");
   # saving the b2b key into the local cache
   cache_store("local","some_b2bl_key_identifier","$avp(99)");
   ...
}

route(Y)
{
   # handling calls to bridge to existing b2b calls
   ...
   # retrieving the key of a b2b call
   cache_fetch("local","some_b2bl_key_identifier", $avp(98) );
   $var(entity) = 1;
   b2b_bridge_request("$avp(98)","$var(entity)");
   ...
}
...

1.5. Exported MI Functions

1.5.1.  b2b_trigger_scenario

   This command instantiated a B2B scenario.

   Name: b2b_trigger_scenario

   Parameters:
     * senario_id : the id of the scenario to be instantiated.
     * scenario parameters - it can take 4 more parameters that
       are scenario parameters

   MI FIFO Command Format:
        :b2b_trigger_scenario:fifo_reply
        marketing
        sip:bob@opensips.org
        sip:322@opensips.org:5070
        sip:alice@opensips.org
        _empty_line_

1.5.2.  b2b_bridge

   This command can be used by an external application to tell
   B2BUA to bridge a call party from an on going dialog to another
   destination. By default the caller is bridged to the new uri
   and BYE is set to the callee. You can instead bridge the callee
   if you send 1 as the third parameter. Also, if a fourth
   parameter is

   Name: b2b_bridge

   Parameters:
     * dialog-id : the id of the dialog. If you set the module
       parameter dialog-id the server will include the dialogid in
       the generated Invites as the content of a header with name
       'Dialog-ID'.
     * new uri - the uri of the new destination
     * flag to specify that the callee must be bridged to the new
       destination. It is optional. If not present the caller will
       be bridged.
     * provisional media uri - the uri of a media server able to
       play provisional media starting from the beginning of the
       bridging scenario to the end of it. It is optional. If not
       present, no other entity will be envolved in the bridging
       scenario

   MI FIFO Command Format:
        :b2b_bridge:fifo_reply
        1020.30
        sip:alice@opensips.org
        _empty_line_

   opensipsctl Command Format:
        opensipsctl b2b_bridge 1020.30 sip:alice@opensips.org

1.5.3.  b2b_list

   This command can be used to list the internals of b2b_logic
   entities.

   Name: b2b_list

   Parameters: none

   MI FIFO Command Format:
        :b2b_list:_reply_fifo_file_
        _empty_line_

   opensipsctl Command Format:
        opensipsctl fifo b2b_list

Chapter 2. Developer Guide

   The module provides an API that can be used from other OpenSIPS
   modules. The API offers the functions for instantiating b2b
   scenarios from other modules (this comes as an addition to the
   other two means of instantiating b2b scenarios - from script
   and with an MI command). Also the instantiations can be
   dynamically controlled, by commanding the bridging of an entity
   involved in a call to another entity or the termination of the
   call or even bridging two existing calls.

2.1.  b2b_logic_bind(b2bl_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. b2bl_api_t structure
...
typedef struct b2bl_api
{
        b2bl_init_f init;
        b2bl_bridge_f bridge;
        b2bl_bridge_extern_f bridge_extern;
        b2bl_bridge_2calls_t bridge_2calls;
        b2bl_terminate_call_t terminate_call;
        b2bl_set_state_f set_state;
        b2bl_bridge_msg_t bridge_msg;
}b2bl_api_t;
...

2.2.  init

   Field type:
...
typedef str* (*b2bl_init_f)(struct sip_msg* msg, str* name, str* args[5]
,
                b2bl_cback_f, void* param);
...

   Initializing a b2b scenario. The last two parameters are the
   callback function and the parameter to be called in 3
   situations that will be listed below. The callback function has
   the following definition:
...
typedef int (*b2b_notify_t)(struct sip_msg* msg, str* id, int type, void
* param);
...

   The first argument is the callback given in the init function.

   The second argument is a structure with some statistics about
   the call -start time, setup time, call time.

   The third argument is the current state of the scenario
   instantiation.

   The last argument is the event that triggered the callback.
   There are 3 events when the callback is called:
     * when a BYE is received from either side- event parameter
       will also show from which side the BYE is received, so it
       can be B2B_BYE_E1 or B2B_BYE_E2
     * If while bridging, a negative reply is received from the
       second entity - the event is B2B_REJECT_E2.
     * When the b2b logic entity is deleted- the evnet is
       B2B_DESTROY

   The return code controls what will happen with the
   request/reply that caused the event (except for the last event,
   when the return code does not matter)
     * -1 - error
     * 0 - drop the BYE or reply
     * 1 - send the BYE or reply on the other side
     * 2 - do what the scenario tells, if no rule defined send the
       BYE or reply on the other side

2.3.  bridge

   Field type:
...
typedef int (*b2bl_bridge_f)(str* key, str* new_uri, str* new_from_dname
,int entity_type);
...

   This function allows bridging an entity that is in a call
   handled by b2b_logic to another entity.

2.4.  bridge_extern

   Field type:
...
typedef str* (*b2bl_bridge_extern_f)(str* scenario_name, str* args[5],
                b2bl_cback_f cbf, void* cb_param);
...

   This function allows initiating an extern scenario, when the
   B2BUA starts a call from the middle.

2.5.  bridge_2calls

   Field type:
...
typedef int (*b2bl_bridge_2calls_t)(str* key1, str* key2);
...

   With this function it is possible to bridge two existing calls.
   The first entity from the two calls will be connected and BYE
   will be sent to their peers.

2.6.  terminate_call

   Field type:
...
typedef int (*b2bl_terminate_call_t)(str* key);
...

   Terminate a call.

2.7.  set_state

   Field type:
...
typedef int (*b2bl_set_state_f)(str* key, int state);
...

   Set the scenario state.

2.8.  bridge_msg

   Field type:
...
typedef int (*b2bl_bridge_msg_t)(struct sip_msg* msg, str* key, int enti
ty_no);
...

   This function allows bridging an incoming call to an entity
   from an existing call.

   The first argument is the INVITE message of the current
   incoming call.

   The second argument is the b2bl_key of an existing call.

   The third argument is the entity identifier.
