modules: readme files regenerated - call_control ... [skip ci]
[sip-router] / src / modules / call_control / README
1 Call Control Module
2
3 Dan Pascu
4
5    <dan@ag-projects.com>
6
7 Edited by
8
9 Dan Pascu
10
11    <dan@ag-projects.com>
12
13    Copyright © 2005-2008 Dan Pascu
14      __________________________________________________________________
15
16    Table of Contents
17
18    1. Admin Guide
19
20         1. Overview
21         2. Description
22         3. Features
23         4. Dependencies
24
25               4.1. Kamailio Modules
26               4.2. External Libraries or Applications
27
28         5. Exported parameters
29
30               5.1. disable (int)
31               5.2. socket_name (string)
32               5.3. socket_timeout (int)
33               5.4. signaling_ip_avp (string)
34               5.5. canonical_uri_avp (string)
35               5.6. diverter_avp_id (string)
36
37         6. Functions
38
39               6.1. call_control()
40
41    List of Examples
42
43    1.1. Setting the disable parameter
44    1.2. Setting the socket_name parameter
45    1.3. Setting the socket_timeout parameter
46    1.4. Setting the signaling_ip_avp parameter
47    1.5. Setting the canonical_uri_avp parameter
48    1.6. Setting the diverter_avp_id parameter
49    1.7. Using the call_control function
50
51 Chapter 1. Admin Guide
52
53    Table of Contents
54
55    1. Overview
56    2. Description
57    3. Features
58    4. Dependencies
59
60         4.1. Kamailio Modules
61         4.2. External Libraries or Applications
62
63    5. Exported parameters
64
65         5.1. disable (int)
66         5.2. socket_name (string)
67         5.3. socket_timeout (int)
68         5.4. signaling_ip_avp (string)
69         5.5. canonical_uri_avp (string)
70         5.6. diverter_avp_id (string)
71
72    6. Functions
73
74         6.1. call_control()
75
76 1. Overview
77
78    This module allows one to limit the duration of calls and automatically
79    end them when they exceed the imposed limit. Its main use case is to
80    implement a prepaid system, but it can also be used to impose a global
81    limit on all calls processed by the proxy.
82
83 2. Description
84
85    Callcontrol consists of 3 components:
86      * The Kamailio call_control module
87      * An external application called callcontrol which keeps track of the
88        calls that have a time limit and automatically ends them when they
89        exceed it. This application receives requests from Kamailio and
90        makes requests to a rating engine (see below) to find out if a call
91        needs to be limited or not. When a call ends (or is ended) it will
92        also instruct the rating engine to debit the balance for the caller
93        with the consumed amount. The callcontrol application is available
94        from http://callcontrol.ag-projects.com/
95      * At the moment the callcontrol application only supports the old
96        “MI” interface for communication with Kamailio. This interface is
97        unfortunately not available anymore in Kamailio. So this
98        application can't be used right now together with the call_control
99        module.
100      * A rating engine that is used to calculate the time limit based on
101        the caller's credit and the destination price and to debit the
102        caller's balance after a call ends. This is available as part of
103        CDRTool from http://cdrtool.ag-projects.com/
104
105    The callcontrol application runs on the same machine as Kamailio and
106    they communicate over a filesystem socket, while the rating engine can
107    run on a different host and communicates with the callcontrol
108    application using a TCP connection.
109
110    Callcontrol is invoked by calling the call_control() function for the
111    initial INVITE of every call we want to apply a limit to. This will end
112    up as a request to the callcontrol application, which will interogate
113    the rating engine for a time limit for the given caller and
114    destination. The rating engine will determine if the destination has
115    any associated cost and if the caller has any credit limit and if so
116    will return the amount of time he is allowed to call that destination.
117    Otherwise it will indicate that there is no limit associated with the
118    call. If there is a limit, the callcontrol application will retain the
119    session and attach a timer to it that will expire after the given time
120    causing it to call back to Kamailio with a request to end the dialog.
121    If the rating engine returns that there is no limit for the call, the
122    session is discarded by the callcontrol application and it will allow
123    it to go proceed any limit. An appropriate response is returned to the
124    call_control module that is then returned by the call_control()
125    function call and allows the script to make a decision based on the
126    answer.
127
128 3. Features
129
130      * Very simple API consisting of a single function that needs to be
131        called once for the first INVITE of every call. The rest is done
132        automatically in the background using dialog callbacks.
133      * Gracefully end dialogs when they exceed their time by triggering a
134        dlg_end_dlg request into the dialog module, that will generate two
135        BYE messages towards each endpoint, ending the call cleanly.
136      * Allow parallel sessions using one balance per subscriber
137      * Integrates with mediaproxy's ability to detect when a call does
138        timeout sending media and is closed. In this case the dlg_end_dlg
139        that is triggered by mediaproxy will end the callcontrol session
140        before it reaches the limit and consumes all the credit for a call
141        that died and didn't actually take place. For this mediaproxy has
142        to be used and it has to be started by engage_media_proxy() to be
143        able to keep track of the call's dialog and end it on timeout.
144        Even when mediaproxy is unable to end the dialog because it was not
145        started with engage_media_proxy(), the callcontrol application is
146        still able to detect calls that did timeout sending media, by
147        looking in the radius accounting records for entries recorded by
148        mediaproxy for calls that did timeout. These calls will also be
149        ended gracefully by the callcontrol application itself.
150
151 4. Dependencies
152
153    4.1. Kamailio Modules
154    4.2. External Libraries or Applications
155
156 4.1. Kamailio Modules
157
158    The following modules must be loaded before this module:
159      * pv module
160      * dialog module
161
162 4.2. External Libraries or Applications
163
164    The following libraries or applications must be installed before
165    running Kamailio with this module loaded:
166      * None.
167
168 5. Exported parameters
169
170    5.1. disable (int)
171    5.2. socket_name (string)
172    5.3. socket_timeout (int)
173    5.4. signaling_ip_avp (string)
174    5.5. canonical_uri_avp (string)
175    5.6. diverter_avp_id (string)
176
177 5.1. disable (int)
178
179    Boolean flag that specifies if callcontrol should be disabled. This is
180    useful when you want to use the same Kamailio configuration in two
181    different contexts, one using callcontrol, the other not. In the case
182    callcontrol is disabled, calls to the call_control() function will
183    return a code indicating that there is no limit associated with the
184    call, allowing the use of the same configuration without changes.
185
186    Default value is “0”.
187
188    Example 1.1. Setting the disable parameter
189 ...
190 modparam("call_control", "disable", 1)
191 ...
192
193 5.2. socket_name (string)
194
195    The path to the filesystem socket where the callcontrol application
196    listens for commands from the module.
197
198    Default value is “/var/run/callcontrol/socket”.
199
200    Example 1.2. Setting the socket_name parameter
201 ...
202 modparam("call_control", "socket_name", "/var/run/callcontrol/socket")
203 ...
204
205 5.3. socket_timeout (int)
206
207    How long time (in milliseconds) to wait for an answer from the
208    callcontrol application.
209
210    Default value is “500” ms.
211
212    Example 1.3. Setting the socket_timeout parameter
213 ...
214 modparam("call_control", "socket_timeout", 500)
215 ...
216
217 5.4. signaling_ip_avp (string)
218
219    Specification of the AVP which holds the IP address from where the SIP
220    signaling originated. If this AVP is set it will be used to get the
221    signaling IP address, else the source IP address from where the SIP
222    message was received will be used. This AVP is meant to be used in
223    cases where there are more than one proxy in the call setup path and
224    the proxy that actually starts callcontrol doesn't receive the SIP
225    messages directly from the UA and it cannot determine the NAT IP
226    address from where the signaling originated. In such a case attaching a
227    SIP header at the first proxy and then copying that header's value into
228    the signaling_ip_avp on the proxy that starts callcontrol will allow it
229    to get the correct NAT IP address from where the SIP signaling
230    originated.
231
232    This is used by the rating engine which finds the rates to apply to a
233    call based on caller's SIP URI, caller's SIP domain or caller's IP
234    address (whichever yields a rate first, in this order).
235
236    Default value is “$avp(s:signaling_ip)”.
237
238    Example 1.4. Setting the signaling_ip_avp parameter
239 ...
240 modparam("call_control", "signaling_ip_avp", "$avp(s:signaling_ip)")
241 ...
242
243 5.5. canonical_uri_avp (string)
244
245    Specification of the AVP which holds an optional application defined
246    canonical request URI. When this is set, it will be used as the
247    destination when computing the call price, otherwise the request URI
248    will be used. This is useful when the username of the ruri needs to
249    have a different, canonical form in the rating engine computation than
250    it has in the ruri.
251
252    Default value is “$avp(s:can_uri)”.
253
254    Example 1.5. Setting the canonical_uri_avp parameter
255 ...
256 modparam("call_control", "canonical_uri_avp", "$avp(s:can_uri)")
257 ...
258
259 5.6. diverter_avp_id (string)
260
261    Specification of the id of an integer AVP which holds an optional
262    application defined diverter SIP URI. When this is set, it will be used
263    by the rating engine as the billing party when finding the rates to
264    apply to a given call, otherwise, the caller's URI taken from the From
265    field will be used. When set, this AVP should contain a value in the
266    form “user@domain” (no sip: prefix should be used).
267
268    This is useful when a destination diverts a call, thus becoming the new
269    caller. In this case the billing party is the diverter and this AVP
270    should be set to it, to allow the rating engine to pick the right rates
271    for the call. For example, if A calls B and B diverts all its calls
272    unconditionally to C, then the diverter AVP should the set to B's URI,
273    because B is the billing party in the call not A after the call was
274    diverted.
275
276    Default value is “805”.
277
278    Example 1.6. Setting the diverter_avp_id parameter
279 ...
280 modparam("call_control", "diverter_avp_id", 805)
281
282 route {
283   ...
284   # alice@example.com is paying for this call
285   $avp(i:805) = "sip:alice@example.com";
286   ...
287 }
288 ...
289
290 6. Functions
291
292    6.1. call_control()
293
294 6.1. call_control()
295
296    Trigger the use of callcontrol for the dialog started by the INVITE for
297    which this function is called (the function should only be called for
298    the first INVITE of a call). Further in-dialog requests will be
299    processed automatically using internal bindings into the dialog state
300    machine, allowing callcontrol to update its internal state as the
301    dialog progresses, without any other intervention from the script.
302
303    This function should be called right before the message is sent out
304    using t_relay(), when all the request uri modifications are over and a
305    final destination has been determined.
306
307    This function has the following return codes:
308
309      * +2 - call has no limit
310      * +1 - call has limit and is traced by callcontrol
311      * -1 - not enough credit to make the call
312      * -2 - call is locked by another call in progress
313      * -5 - internal error (message parsing, communication, ...)
314
315    This function can be used from REQUEST_ROUTE.
316
317    Example 1.7. Using the call_control function
318 ...
319 if (is_avp_set("$avp(i:805)")) {
320     # the diverter AVP is set, use it as billing party
321     $avp(s:billing_party_domain) = $(avp(i:805){uri.domain});
322 } else {
323     $avp(s:billing_party_domain) = $fd;
324 }
325
326 if (method==INVITE && !has_totag() &&
327     is_domain_local("$avp(s:billing_party_domain)")) {
328     call_control();
329     switch ($retcode) {
330     case 2:
331         # Call with no limit
332     case 1:
333         # Call has limit and is under callcontrol management
334         break;
335     case -1:
336         # Not enough credit (prepaid call)
337         sl_send_reply("402", "Not enough credit");
338         exit;
339         break;
340     case -2:
341         # Locked by another call in progress (prepaid call)
342         sl_send_reply("403", "Call locked by another call in progress");
343         exit;
344         break;
345     default:
346         # Internal error (message parsing, communication, ...)
347         if (PREPAID_ACCOUNT) {
348             xlog("Call control: internal server error\n");
349             sl_send_reply("500", "Internal server error");
350             exit;
351         } else {
352             xlog("L_WARN", "Cannot set time limit for postpaid call\n");
353         }
354     }
355 }
356 t_relay();
357 ...