B2B_LOGIC_XML


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(flags, [scenario_param1], [scenario_param2], [scenario_param3], [scenario_param4])
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
1.6. Exported Pseudo-Variables
1.6.1. $b2b_logic.key
1.6.2. $b2b_logic.entity(field)[idx]
1.6.3. $b2b_logic.ctx(key)
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
3. Contributors
3.1. By Commit Statistics
3.2. By Commit Activity
4. Documentation
4.1. Contributors

List of Tables

3.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
3.2. Most recently active contributors(1) to this module

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
1.19. $b2b_logic.key usage
1.20. $b2b_logic.entity usage
1.21. $b2b_logic.ctx usage
2.1. b2bl_api_t structure

Chapter 1. Admin Guide

1.1. Overview

Note

This module is deprecated and will be removed in the next major OpenSIPS version! The module is a duplicate of the legacy b2b_logic module and offers the possiblity to use XML scenario files in order to implement B2BUA logic. Since OpenSIPS version 3.2, the b2b_logic module only uses OpenSIPS scripting for controlling its behavior.

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_xml 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).

High Availability for B2B sessions can be achieved by enabling the clustering support offered by the the lower b2b_entities module (by setting the cluster_id modparam from b2b_entities).

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_xml", "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_xml", "script_scenario", "/usr/local/opensips/scripts/b2b_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_xml", "extern_scenario", "/usr/local/opensips/scripts/b2b_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_xml", "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_xml", "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_xml", "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_xml", "use_init_sdp", 1)
...
	

1.3.8. db_url (str)

Database URL.

Example 1.8. Set db_url parameter

...
modparam("b2b_logic_xml", "db_url", "mysql://opensips:opensipsrw@127.0.0.1/opensips")
...
	

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_xml", "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_xml", "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_xml", "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_xml", "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_xml", "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_xml", "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_xml", "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_xml", "b2bl_th_init_timeout", 60)
...
	

1.4. Exported Functions

1.4.1.  b2b_init_request(flags, [scenario_param1], [scenario_param2], [scenario_param3], [scenario_param4])

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". 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.

Parameters:

  • flags (string) - 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.

  • scenario_param1 (string, optional)

  • scenario_param2 (string, optional)

  • scenario_param3 (string, optional)

  • scenario_param4 (string, optional)

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 (string) - a string that contains the b2b_logic key. The key can also be in the form of callid;from-tag;to-tag.

  • entity_no (int) - an integer that holds the entity of the entity/participant to bridge.

Example 1.18. b2b_bridge_request usage

...
modparam("b2b_entities", "script_req_route", "b2b_request")
...
route[b2b_request]
{
   # incoming requests from the B2B entities
   ...
   if ($ci~="^B2B") { #keep this aligned with b2b_key_prefix
      # request coming from the UAC side;
      # the Call-ID carries the B2B key ID
      if (is_method("BYE") {
         $var(entity) = 1;
         b2b_bridge_request($ci,$var(entity));
      }
   }
   ...
}
...
		

1.5. Exported MI Functions

1.5.1.  b2b_trigger_scenario

This command instantiates a B2B scenario.

Name: b2b_trigger_scenario

Parameters:

  • senario_id : the id of the scenario to be instantiated.

  • scenario_params - array of at least 2 scenario parameters

MI FIFO Command Format:

	opensips-cli -x mi b2b_trigger_scenario marketing sip:bob@opensips.org sip:322@opensips.org:5070 sip:alice@opensips.org
		

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.

Name: b2b_bridge

Parameters:

  • dialog_id : the b2b_logic key, or the callid;from-tag;to-tag of the ongoing dialog.

  • new_uri - the uri of the new destination

  • flag (optional) - used to specify that the callee must be bridged to the new destination. If not present the caller will be bridged. Possible values are '0' or '1'.

  • prov_media_uri (optional) - 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:

	opensips-cli -x mi b2b_bridge 1020.30 sip:alice@opensips.org
	

opensips-cli Command Format:

	opensips-cli -x mi 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:

    	opensips-cli -x mi b2b_list
    	

    1.6. Exported Pseudo-Variables

    1.6.1.  $b2b_logic.key

    This is a read-only variable that returns the b2b_logic key of the ongoing B2B session.

    The variable can be used in request route, local_route and in the custom B2B request and reply routes defined through the b2b_entities module.

    Example 1.19. $b2b_logic.key usage

    ...
    local_route {
       ...
       if ($b2b_logic.key) {
          xlog("request belongs to B2B session: $b2b_logic.key\n");
          ...
       }
       ...
    }
    ...
    	

    1.6.2.  $b2b_logic.entity(field)[idx]

    This is a read-only variable that returns information about the entities(dialogs) involved in the ongoing B2B session.

    The available entity information is:

    • the Call-ID of the dialog, accessible by using the callid subname;

    • the entity key, accessible by using the key subname or no subname at all.

    The index is used to select which entity from the B2B session to refer to. The only possible values are 0 or 1 and correspond to the positions of the entities in the scenario. Initially, this depends on the order of the entities in the init section of the scenario file. In the case of the internal topology hiding scenario, 0 is the caller and 1 is the callee. When a further bridge action happens, the bridged entity is always placed on the 0 index and the new entity on 1.

    If no index is provided, the variable will refer to the entity(dialog) which the current SIP message belongs to.

    The variable can be used in request route, local_route and in the custom B2B request and reply routes defined through the b2b_entities module.

    Example 1.20. $b2b_logic.entity usage

    ...
    modparam("b2b_entities", "script_request_route", "b2b_request")
    ...
    route[b2b_request] {
       ...
       xlog("received request for entity: $b2b_logic.entity\n");
       ...
       if ($rm == "BYE" && $b2b_logic.entity == $(b2b_logic.entity[1]))
          xlog("Disconnecting callee\n")
       ...
    }
    ...
    	

    1.6.3.  $b2b_logic.ctx(key)

    This is a read-write variable that provides access to a custom Key-Value storage(of string values) in the context of the ongoing B2B session.

    The variable can be used in request route, local_route and in the custom B2B request and reply routes defined through the b2b_entities module. In the main request route the variable can be used for storing a new context value even before instantiating the scenario with b2b_init_request().

    Setting the variable to NULL will delete the value at the given key.

    Example 1.21. $b2b_logic.ctx usage

    ...
    modparam("b2b_entities", "script_reply_route", "b2b_reply")
    ...
    route {
       ...
       b2b_init_request("prepaid", "sip:alice@127.0.0.1");
    
       $b2b_logic.ctx(my_extra_info) = "my_value";
       ...
    }
    ...
    route[b2b_reply] {
       ...
       xlog("my info: $b2b_logic.ctx(my_extra_info)\n");
       ...
    }
    ...
    	

    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 entity_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.

    Chapter 3. Contributors

    3.1. By Commit Statistics

    Table 3.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)

     NameDevScoreCommitsLines ++Lines --
    1. Anca Vamanu2099890082213
    2. Ovidiu Sas (@ovidiusas)14410129151129
    3. Vlad Patrascu (@rvlad-patrascu)1422513122583
    4. Bogdan-Andrei Iancu (@bogdan-iancu)4235243258
    5. Razvan Crainea (@razvancrainea)4231700269
    6. Liviu Chircu (@liviuchircu)151255100
    7. Nick Altmann (@nikbyte)146461199
    8. Vlad Paiu (@vladpaiu)753521
    9. Maksym Sobolyev (@sobomax)5399
    10. Peter Lemenkov (@lemenkov)4222

    All remaining contributors: Dan Pascu (@danpascu), Ezequiel Lovelle (@lovelle), Walter Doekes (@wdoekes), Zero King (@l2dy).

    (1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)

    (2) including any documentation-related commits, excluding merge commits. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".

    (3) ignoring whitespace edits, renamed files and auto-generated files

    3.2. By Commit Activity

    Table 3.2. Most recently active contributors(1) to this module

     NameCommit Activity
    1. Razvan Crainea (@razvancrainea)Jun 2011 - Feb 2022
    2. Vlad Patrascu (@rvlad-patrascu)May 2017 - Jul 2021
    3. Bogdan-Andrei Iancu (@bogdan-iancu)Aug 2009 - Apr 2021
    4. Maksym Sobolyev (@sobomax)Oct 2020 - Jan 2021
    5. Liviu Chircu (@liviuchircu)Mar 2014 - Jul 2020
    6. Zero King (@l2dy)Mar 2020 - Mar 2020
    7. Peter Lemenkov (@lemenkov)Jun 2018 - Feb 2020
    8. Dan Pascu (@danpascu)Jul 2019 - Jul 2019
    9. Walter Doekes (@wdoekes)Apr 2019 - Apr 2019
    10. Ovidiu Sas (@ovidiusas)Nov 2010 - Mar 2016

    All remaining contributors: Ezequiel Lovelle (@lovelle), Nick Altmann (@nikbyte), Anca Vamanu, Vlad Paiu (@vladpaiu).

    (1) including any documentation-related commits, excluding merge commits

    Chapter 4. Documentation

    4.1. Contributors

    Last edited by: Vlad Patrascu (@rvlad-patrascu), Razvan Crainea (@razvancrainea), Liviu Chircu (@liviuchircu), Peter Lemenkov (@lemenkov), Bogdan-Andrei Iancu (@bogdan-iancu), Nick Altmann (@nikbyte), Ovidiu Sas (@ovidiusas), Vlad Paiu (@vladpaiu), Anca Vamanu.

    Documentation Copyrights:

    Copyright © 2010 VoIP Embedded, Inc.

    Copyright © 2009 Anca-Maria Vamanu