mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
195 lines
5.2 KiB
195 lines
5.2 KiB
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;
|
|
}
|
|
...
|
|
}
|