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
draft-levy-sip-diversion-08. 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

The draft-levy-sip-diversion-08 is expired!! See IETF I-D tracker.

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:[email protected] is:
INVITE sip:[email protected] SIP/2.0
Via: SIP/2.0/UDP 1.2.3.4:5060
From: "mark" ;tag=ldgheoihege
To: "Bob"
Call-ID: [email protected]
CSeq: 3 INVITE
Contact:
Content-Length: 0

The INVITE message is diverted by the user agent of sip:[email protected]
because the user was talking to someone else and the new destination is
sip:[email protected] :
INVITE sip:[email protected] 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" ;tag=ldgheoihege
To: "Bob"
Call-ID: [email protected]
CSeq: 3 INVITE
Diversion: ;reason=user-busy
Contact:
Content-Length: 0

Chapter 2. Developer Guide

According to the specification 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, 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;
}
...
}