1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
%docentities;
]>
<!-- Module User's Guide -->
<chapter>
<title>&adminguide;</title>
<section id="diversion.overview">
<title>Overview</title>
<para>
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.
</para>
<warning><para>
Note that RFC 5806 has historic status.
</para></warning>
</section>
<section>
<title>Dependencies</title>
<section>
<title>&kamailio; Modules</title>
<para>None.</para>
</section>
<section>
<title>External Libraries or Applications</title>
<para>
The following libraries or applications must be installed before running
&kamailio; with this module loaded:
<itemizedlist>
<listitem>
<para>
<emphasis>None</emphasis>.
</para>
</listitem>
</itemizedlist>
</para>
</section>
</section>
<section>
<title>Parameters</title>
<section id="diversion.p.suffix">
<title><varname>suffix</varname> (string)</title>
<para>
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.
</para>
<para>
Default value is <quote></quote> (empty string).
</para>
<example>
<title><varname>suffix</varname> usage</title>
<programlisting format="linespecific">
modparam("diversion", "suffix", ";privacy=full")
</programlisting>
</example>
</section>
</section>
<section>
<title>Functions</title>
<section id="diversion.f.add_diversion">
<title><function moreinfo="none">add_diversion(reason [, uri])</function></title>
<para>
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.
</para>
<para>Meaning of the parameters is as follows:</para>
<itemizedlist>
<listitem>
<para><emphasis>reason</emphasis> - The reason string to be added
as the reason parameter
</para>
</listitem>
<listitem>
<para><emphasis>uri</emphasis> - The URI to be set in Diversion header
</para>
</listitem>
</itemizedlist>
<para>
The parameters can contain pseudo-variables.
</para>
<para>
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
</para>
<example>
<title><function moreinfo="none">add_diversion</function> usage</title>
<programlisting format="linespecific">
...
add_diversion("user-busy");
add_diversion("user-busy", "$ru");
...
</programlisting>
</example>
</section>
</section>
<section>
<title>Diversion Example</title>
<para>
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:
</para>
<programlisting format="linespecific">
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
</programlisting>
<para>
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 :
</para>
<programlisting format="linespecific">
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
</programlisting>
</section>
</chapter>
|
