README
1utils
2
3Juha Heinanen
4
5 TutPro Inc.
6
7Carsten Bock
8
9 ng-voice GmbH
10
11 Copyright © 2008-2009 Juha Heinanen
12
13 Copyright © 2013-2015 Carsten Bock, ng-voice GmbH
14 __________________________________________________________________
15
16 Table of Contents
17
18 1. Admin Guide
19
20 1. Overview
21 2. Dependencies
22
23 2.1. Kamailio Modules
24 2.2. External Libraries or Applications
25
26 3. Parameters
27
28 3.1. forward_active (int)
29 3.2. pres_db_url (string)
30 3.3. xcap_table (string)
31
32 4. Functions
33
34 4.1. xcap_auth_status(watcher_uri, presentity_uri)
35
36 5. MI Commands
37
38 5.1. forward_list
39 5.2. forward_switch
40 5.3. forward_filter
41 5.4. forward_proxy
42
43 6. Configuration syntax
44
45 List of Examples
46
47 1.1. Set forward_active parameter
48 1.2. Set pres_db_url parameter
49 1.3. Set xcap_table parameter
50 1.4. xcap_auth_status() usage
51 1.5. forward_list usage
52 1.6. forward_switch usage
53 1.7. forward_filter usage
54 1.8. forward_proxy usage
55
56Chapter 1. Admin Guide
57
58 Table of Contents
59
60 1. Overview
61 2. Dependencies
62
63 2.1. Kamailio Modules
64 2.2. External Libraries or Applications
65
66 3. Parameters
67
68 3.1. forward_active (int)
69 3.2. pres_db_url (string)
70 3.3. xcap_table (string)
71
72 4. Functions
73
74 4.1. xcap_auth_status(watcher_uri, presentity_uri)
75
76 5. MI Commands
77
78 5.1. forward_list
79 5.2. forward_switch
80 5.3. forward_filter
81 5.4. forward_proxy
82
83 6. Configuration syntax
84
851. Overview
86
87 This module implements various utility functions that are not SIP
88 related.
89
90 The forward functionality allows Kamailio to configure forwarding at
91 runtime with FIFO commands. The forwarding is executed in the pre
92 script call back and therefore handled before the routing script is
93 executed on the current message. The callback is not installed on
94 default, thus this functionality has no runtime overhead when its
95 deactivated.
96
97 Function xcap_auth_status can be used to check from presence server
98 database, if watcher is authorized to subscribe event “presence” of
99 presentity.
100
1012. Dependencies
102
103 2.1. Kamailio Modules
104 2.2. External Libraries or Applications
105
1062.1. Kamailio Modules
107
108 The following modules must be loaded before this module:
109 * a database module if xcap_auth_status function is enabled.
110
1112.2. External Libraries or Applications
112
113 The following libraries or applications must be installed before
114 running Kamailio with this module loaded:
115 * none.
116
1173. Parameters
118
119 3.1. forward_active (int)
120 3.2. pres_db_url (string)
121 3.3. xcap_table (string)
122
1233.1. forward_active (int)
124
125 Defines if the forwarding callback should be installed.
126
127 Default value is “0” - disabled.
128
129 Example 1.1. Set forward_active parameter
130 ...
131 modparam("utils", "forward_active", 1)
132 ...
133
1343.2. pres_db_url (string)
135
136 Defines presence server database URL. If not given, the
137 xcap_auth_status function is disabled.
138
139 There is no default value.
140
141 Example 1.2. Set pres_db_url parameter
142...
143modparam("utils", "pres_db_url", "mysql://foo:secret@localhost/pres")
144...
145
1463.3. xcap_table (string)
147
148 Defines the name of the xcap table in the presence server database. See
149 the xcap_server module documentation for more information.
150
151 Default value is “xcap”.
152
153 Example 1.3. Set xcap_table parameter
154...
155modparam("utils", "xcap_table", "pres_xcap")
156...
157
1584. Functions
159
160 4.1. xcap_auth_status(watcher_uri, presentity_uri)
161
1624.1. xcap_auth_status(watcher_uri, presentity_uri)
163
164 Function checks in the presence server database if a watcher is
165 authorized to subscribe to event “presence” of presentity. Sphere
166 checking is not included.
167
168 Both watcher_uri and presentity_uri are pseudo variables. The function
169 returns ACTIVE_STATUS, if a subscription is allowed and PENDING_STATUS,
170 TERMINATED_STATUS, or WAITING_STATUS otherwise. See
171 presence/subscribe.h for the corresponding integer codes. In case of
172 error, function returns -1.
173
174 Function can be used from REQUEST_ROUTE.
175
176 Example 1.4. xcap_auth_status() usage
177...
178if (method=="MESSAGE") {
179 xcap_auth_status("$fu", $ru");
180 if ($retcode == 1) {
181 t_relay();
182 } else {
183 send_reply("403", "Forbidden");
184 }
185}
186...
187
1885. MI Commands
189
190 5.1. forward_list
191 5.2. forward_switch
192 5.3. forward_filter
193 5.4. forward_proxy
194
1955.1. forward_list
196
197 List active forward rules.
198
199 No parameters.
200
201 Example 1.5. forward_list usage
202...
203kamctl fifo forward_list
204id switch filter proxy
205 0 off REGISTER:INVITE:SUBSCRIBE host-a.domain-a:5060
206...
207
2085.2. forward_switch
209
210 This command can be used to activate or deactivate forwarding rules.
211 The syntax of this configuration string is described in 1.6.
212 (switch_setting_list).
213
214 Example 1.6. forward_switch usage
215...
216kamctl fifo forward_switch 0=on
217...
218
2195.3. forward_filter
220
221 Can be used to specify the filter for a certain id. Messages will only
222 be forwarded if one of the filters matches the message.
223
224 There are special filters and regular filters. Special filters are:
225 * REQUEST (matches on every request)
226 * REPLY (matches on every reply)
227
228 Regular filters are arbitrary strings not containing the delimiter ':'.
229 They are matched against the request method names of the sip messages.
230 The syntax of this configuration string is described in 1.6.
231 (filter_setting_list).
232
233 Example 1.7. forward_filter usage
234...
235kamctl fifo forward_filter 0=REGISTER:INVITE
236...
237
2385.4. forward_proxy
239
240 This command can be used to configure forwarding rules. Specifies the
241 destination for a certain id. Messages will be forwarded to this
242 destination if the preconditions hold (matching id, filter, and
243 switch). The syntax of this configuration string is described in 1.6.
244 (proxy_setting_list).
245
246 Example 1.8. forward_proxy usage
247...
248kamctl fifo forward_proxy 0=host-c.domain-c:5060
249...
250
2516. Configuration syntax
252
253 This grammar specify the usable configuration syntax
254 * switch_setting_list ::= switch_setting { "," switch_setting }
255 * filter_setting_list ::= switch_setting { "," switch_setting }
256 * proxy_setting_list ::= proxy_setting { "," proxy_setting }
257 * switch_setting ::= id "=" switch
258 * filter_setting ::= id "=" filter_list
259 * proxy_setting ::= id "=" proxy
260 * switch ::= ( "off" | "on" )
261 * filter_list ::= filter { ":" filter }
262 * proxy ::= host ":" port
263 * filter ::= ( special_filter | regular_filter )
264 * special_filter ::= ( "REQUEST" | "REPLY" )
265 * regular_filter ::= ? [^:]* ?
266 * host ::= char { char }
267 * char ::= ? A-Za-z0-9.-_ ?
268 * id ::= number
269 * port ::= number
270 * number ::= digit {digit}
271 * digit ::= ? 0-9 ?
272