kamailio/modules/diversion

Diversion Module

Jan Janak

   FhG FOKUS

Edited by

Jan Janak

   Copyright © 2004 FhG FOKUS
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. suffix (string)

        4. Functions

              4.1. add_diversion(reason [, uri])

        5. Diversion Example

   2. Developer Guide

   List of Examples

   1.1. suffix usage
   1.2. add_diversion usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Parameters

        3.1. suffix (string)

   4. Functions

        4.1. add_diversion(reason [, uri])

   5. Diversion Example

1. Overview

   The module implements the Diversion extensions as per RFC 5806. The
   diversion extensions are useful in various scenarios involving call
   forwarding. Typically one needs to communicate the original recipient
   of the call to the PSTN gateway and this is what the diversion
   extensions can be used for.

Warning

   Note that RFC 5806 has historic status.

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   None.

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * None.

3. Parameters

   3.1. suffix (string)

3.1. suffix (string)

   The suffix to be appended to the end of the header field. You can use
   the parameter to specify additional parameters to be added to the
   header field, see the example.

   Default value is “” (empty string).

   Example 1.1. suffix usage
modparam("diversion", "suffix", ";privacy=full")

4. Functions

   4.1. add_diversion(reason [, uri])

4.1. add_diversion(reason [, uri])

   The function adds a new diversion header field before any other
   existing Diversion header field in the message (the newly added
   Diversion header field will become the topmost Diversion header field).
   If 'uri' parameter is missing, the inbound (without any modifications
   done by the proxy server) Request-URI will be used as the Diversion
   URI.

   Meaning of the parameters is as follows:
     * reason - The reason string to be added as the reason parameter
     * uri - The URI to be set in Diversion header

   The parameters can contain pseudo-variables.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
   BRANCH_ROUTE.

   Example 1.2. add_diversion usage
...
add_diversion("user-busy");
add_diversion("user-busy", "$ru");
...

5. Diversion Example

   The following example shows a Diversion header field added to INVITE
   message. The original INVITE received by the user agent of
   sip:bob@sip.org is:
INVITE sip:bob@sip.org SIP/2.0
Via: SIP/2.0/UDP 1.2.3.4:5060
From: "mark" <sip:mark@sip.org>;tag=ldgheoihege
To: "Bob" <sip:bob@sip.org>
Call-ID: adgasdkgjhkjha@1.2.3.4
CSeq: 3 INVITE
Contact: <sip:mark@1.2.3.4>
Content-Length: 0

   The INVITE message is diverted by the user agent of sip:bob@sip.org
   because the user was talking to someone else and the new destination is
   sip:alice@sip.org :
INVITE sip:alice@sip.org SIP/2.0
Via: SIP/2.0/UDP 5.6.7.8:5060
Via: SIP/2.0/UDP 1.2.3.4:5060
From: "mark" <sip:mark@sip.org>;tag=ldgheoihege
To: "Bob" <sip:bob@sip.org>
Call-ID: adgasdkgjhkjha@1.2.3.4
CSeq: 3 INVITE
Diversion: <sip:bob@sip.org>;reason=user-busy
Contact: <sip:mark@1.2.3.4>
Content-Length: 0

Chapter 2. Developer Guide

   According to the specification a new “Diversion” header field should be
   inserted as the topmost Diversion header field in the message, that
   means before any other existing Diversion header field in the message.
   In addition to that, the add_diversion function can be called several
   times and each time it should insert the new Diversion header field as
   the topmost one.

   In order to implement this, add_diversion function creates the anchor
   in data_lump lists as a static variable to ensure that the next call of
   the function will use the same anchor and would insert new Diversion
   headers before the one created in the previous execution. To my
   knowledge this is the only way of inserting the diversion header field
   before any other created in previous runs of the function.

   The anchor kept this way is only valid for a single message and we have
   to invalidate it when another message is being processed. For this
   reason, the function also stores the id of the message in another
   static variable and compares the value of that variable with the id of
   the SIP message being processed. If they differ then the anchor will be
   invalidated and the function creates a new one.

   The following code snippet shows the code that invalidates the anchor,
   new anchor will be created when the anchor variable is set to 0.
static inline int add_diversion_helper(struct sip_msg* msg, str* s)
{
    static struct lump* anchor = 0;
    static int msg_id = 0;

    if (msg_id != msg->id) {
        msg_id = msg->id;
        anchor = 0;
    }
...
}