modules: readme files regenerated - pv ... [skip ci]
[sip-router] / src / modules / pv / README
1 Pseudo-Variables Module
2
3 Daniel-Constantin Mierla
4
5    asipto.com
6    <daniel@asipto.com>
7
8 Edited by
9
10 Daniel-Constantin Mierla
11
12    <daniel@asipto.com>
13
14    Copyright © 2008-2011 Daniel-Constantin Mierla (asipto.com)
15
16    Copyright © 2011 Juha Heinanen
17
18    Copyright © 2013 Olle E. Johansson, Edvina AB
19      __________________________________________________________________
20
21    Table of Contents
22
23    1. Admin Guide
24
25         1. Overview
26         2. Dependencies
27
28               2.1. Kamailio Modules
29               2.2. External Libraries or Applications
30
31         3. Parameters
32
33               3.1. shvset (string)
34               3.2. varset (string)
35               3.3. avp_aliases (string)
36
37         4. Functions
38
39               4.1. pv_isset(pvar)
40               4.2. pv_unset(pvar)
41               4.3. is_int(pvar)
42               4.4. typeof(pvar, vtype)
43               4.5. not_empty(pvar)
44               4.6. xavp_params_explode(sparams, xname)
45               4.7. sbranch_set_ruri()
46               4.8. sbranch_append()
47               4.9. sbranch_reset()
48               4.10. pv_xavp_print()
49               4.11. pv_var_to_xavp(varname, xname)
50               4.12. pv_xavp_to_var(xname)
51               4.13. pv_evalx(dst, fmt)
52
53         5. RPC Commands
54
55               5.1. pv.shvSet
56               5.2. pv.shvGet
57
58    List of Examples
59
60    1.1. shvset parameter usage
61    1.2. varset parameter usage
62    1.3. avp_aliases parameter usage
63    1.4. pv_isset usage
64    1.5. pv_unset usage
65    1.6. is_int() usage
66    1.7. typeof() usage
67    1.8. not_empty() usage
68    1.9. xavp_params_explode usage
69    1.10. sbranch_set_ruri() usage
70    1.11. sbranch_append() usage
71    1.12. sbranch_append() usage
72    1.13. pv_xavp_print() usage
73    1.14. pv_var_to_xavp() usage
74    1.15. pv_xavp_to_var() usage
75    1.16. pv_xavp_to_var() usage
76    1.17. pv.shvSet usage
77    1.18. pv.shvGet usage
78
79 Chapter 1. Admin Guide
80
81    Table of Contents
82
83    1. Overview
84    2. Dependencies
85
86         2.1. Kamailio Modules
87         2.2. External Libraries or Applications
88
89    3. Parameters
90
91         3.1. shvset (string)
92         3.2. varset (string)
93         3.3. avp_aliases (string)
94
95    4. Functions
96
97         4.1. pv_isset(pvar)
98         4.2. pv_unset(pvar)
99         4.3. is_int(pvar)
100         4.4. typeof(pvar, vtype)
101         4.5. not_empty(pvar)
102         4.6. xavp_params_explode(sparams, xname)
103         4.7. sbranch_set_ruri()
104         4.8. sbranch_append()
105         4.9. sbranch_reset()
106         4.10. pv_xavp_print()
107         4.11. pv_var_to_xavp(varname, xname)
108         4.12. pv_xavp_to_var(xname)
109         4.13. pv_evalx(dst, fmt)
110
111    5. RPC Commands
112
113         5.1. pv.shvSet
114         5.2. pv.shvGet
115
116 1. Overview
117
118    This module collects the core pseudo-variables that can be used in
119    configuration file. They are listed in Dokuwiki:
120    http://www.kamailio.org/wiki/, in Pseudo-Variables section
121
122 2. Dependencies
123
124    2.1. Kamailio Modules
125    2.2. External Libraries or Applications
126
127 2.1. Kamailio Modules
128
129    The following modules must be loaded before this module:
130      * No dependencies on other Kamailio modules.
131
132 2.2. External Libraries or Applications
133
134    The following libraries or applications must be installed before
135    running Kamailio with this module loaded:
136      * None.
137
138 3. Parameters
139
140    3.1. shvset (string)
141    3.2. varset (string)
142    3.3. avp_aliases (string)
143
144 3.1. shvset (string)
145
146    Set the value of a shared variable ($shv(name)). The parameter can be
147    set many times.
148
149    The value of the parameter has the format: _name_ '=' _type_ ':'
150    _value_
151      * _name_: shared variable name
152      * _type_: type of the value
153           + “i”: integer value
154           + “s”: string value
155      * _value_: value to be set
156
157    Default value is “NULL”.
158
159    Example 1.1. shvset parameter usage
160 ...
161 modparam("pv", "shvset", "debug=i:1")
162 modparam("pv", "shvset", "pstngw=s:sip:10.10.10.10")
163 ...
164
165 3.2. varset (string)
166
167    Set the value of a script variable ($var(name)). The parameter can be
168    set many times.
169
170    The value of the parameter has the format: _name_ '=' _type_ ':'
171    _value_
172      * _name_: shared variable name
173      * _type_: type of the value
174           + “i”: integer value
175           + “s”: string value
176      * _value_: value to be set
177
178    Default value is “NULL”.
179
180    Example 1.2. varset parameter usage
181 ...
182 modparam("pv", "varset", "init=i:1")
183 modparam("pv", "varset", "gw=s:sip:11.11.11.11;transport=tcp")
184 ...
185
186 3.3. avp_aliases (string)
187
188    Define aliases for PV AVP names.
189
190    Default value is NULL.
191
192    Example 1.3. avp_aliases parameter usage
193 ...
194 modparam("pv","avp_aliases","email=s:email_addr;tmp=i:100")
195 ...
196
197 4. Functions
198
199    4.1. pv_isset(pvar)
200    4.2. pv_unset(pvar)
201    4.3. is_int(pvar)
202    4.4. typeof(pvar, vtype)
203    4.5. not_empty(pvar)
204    4.6. xavp_params_explode(sparams, xname)
205    4.7. sbranch_set_ruri()
206    4.8. sbranch_append()
207    4.9. sbranch_reset()
208    4.10. pv_xavp_print()
209    4.11. pv_var_to_xavp(varname, xname)
210    4.12. pv_xavp_to_var(xname)
211    4.13. pv_evalx(dst, fmt)
212
213 4.1. pv_isset(pvar)
214
215    Return true if a PV value is different than 'null'.
216
217    Meaning of the parameters is as follows:
218      * pvar - pvar identifier.
219
220    This function can be used from ANY_ROUTE.
221
222    Example 1.4. pv_isset usage
223 ...
224 if(pv_isset("$avp(s:x)"))
225 {
226     ...
227 }
228 ...
229
230 4.2. pv_unset(pvar)
231
232    Unset the value of the PV (e.g., delete AVP, set to null).
233
234    Meaning of the parameters is as follows:
235      * pvar - pvar identifier.
236
237    This function can be used from ANY_ROUTE.
238
239    Example 1.5. pv_unset usage
240 ...
241 pv_unset("$avp(s:x)");
242 ...
243
244 4.3.  is_int(pvar)
245
246    Function checks if pvar argument contains integer value and returns 1
247    if it does and -1 otherwise.
248
249    Function can be used from all kinds of routes.
250
251    Example 1.6. is_int() usage
252 ...
253 if (is_int("$var(foo)")) {
254     xlog("L_INFO", "variable foo contains integer value\n");
255 }
256 ...
257
258 4.4.  typeof(pvar, vtype)
259
260    Returns true if the type of pseudo-variable matches the second
261    parameter. The second parameter can be: 'int' - type is integer; 'str'
262    - type is string; 'null' - type is null.
263
264    Function can be used from ANYROUTE.
265
266    Example 1.7. typeof() usage
267 ...
268 if (typeof("$var(foo)", "str")) {
269     xdbg("variable foo is a string\n");
270 }
271 ...
272
273 4.5.  not_empty(pvar)
274
275    Returns true if the pseudo-variables has the type string and is not
276    empty value.
277
278    Function can be used from all kinds of routes.
279
280    Example 1.8. not_empty() usage
281 ...
282 if (not_empty("$var(foo)")) {
283     append_hf("X-Foo: $var(foo)\r\n");
284 }
285 ...
286
287 4.6.  xavp_params_explode(sparams, xname)
288
289    Convert a parameters string in xavp atributes.
290
291    The first parameter has to be a string in the format of SIP header
292    parameters (name1=value1;...;nameN=valueN). The second parameter is the
293    name of the root xavp to hold the pairs (nameX,valueX).
294
295    The values are stored as string type.
296
297    Function can be used from ANY ROUTE.
298
299    Example 1.9. xavp_params_explode usage
300 ...
301 xavp_params_explode("a=b;c=d;e=d", "x");
302 # results in:
303 #    $xavp(x=>a) = "b";
304 #    $xavp(x=>c) = "d";
305 #    $xavp(x=>e) = "f";
306 ...
307
308 4.7.  sbranch_set_ruri()
309
310    Use the attributes from static branch ($sbranch(key) variable) to set
311    request URI and the other fields of the branch associated with request
312    URI (destination URI, path, ...).
313
314    Content of the static branch is not reset after this function is
315    executed. It has to be done explicitely with sbranch_reset().
316
317    Function can be used from REQUEST_ROUTE, BRANCH_ROUTE or FAILURE_ROUTE.
318
319    Example 1.10. sbranch_set_ruri() usage
320 ...
321 sbranch_reset();
322 $sbranch(uri) = "sip:127.0.0.1:5080";
323 $sbranch(dst_uri) =  "sip:127.0.0.1:5090";
324 $sbranch(path) =  "sip:127.0.0.1:5090, sip:127.0.0.1:5094";
325 $sbranch(send_socket) =  "udp:127.0.0.1:5060";
326 sbranch_set_ruri();
327 ...
328
329 4.8.  sbranch_append()
330
331    Use the attributes from static branch ($sbranch(key) variable) to
332    append a new branch to destination set. It is an alternative to
333    append_branch() that allows setting each attribute specific to the
334    branch.
335
336    Content of the static branch is not reset after this function is
337    executed. It has to be done explicitely with sbranch_reset().
338
339    Function can be used from REQUEST_ROUTE, BRANCH_ROUTE or FAILURE_ROUTE.
340
341    Example 1.11. sbranch_append() usage
342 ...
343 sbranch_reset();
344 $sbranch(uri) = "sip:127.0.0.1:5080";
345 $sbranch(dst_uri) =  "sip:127.0.0.1:5090";
346 $sbranch(send_socket) =  "udp:127.0.0.1:5060";
347 sbranch_append();
348 ...
349
350 4.9.  sbranch_reset()
351
352    Reset the content of static branch ($sbranch(key) variable.
353
354    Function can be used from REQUEST_ROUTE, BRANCH_ROUTE or FAILURE_ROUTE.
355
356    Example 1.12. sbranch_append() usage
357 ...
358 sbranch_reset();
359 ...
360
361 4.10.  pv_xavp_print()
362
363    Print all XAVPs to the syslog using INFO log level.
364
365    Function can be used from ANY_ROUTE.
366
367    Example 1.13. pv_xavp_print() usage
368 ...
369 pv_xavp_print();
370 ...
371
372 4.11.  pv_var_to_xavp(varname, xname)
373
374    Copy the script variable value into an xavp.
375
376    First parameter can be '*' in order to copy all script variables.
377    Second parameter is the name of the destination xavp. If xavp already
378    exists it will be reset first.
379
380    Both parameters can contain variables that are evaluated at runtime.
381
382    Function can be used from ANY_ROUTE.
383
384    Example 1.14. pv_var_to_xavp() usage
385 ...
386 $var("temp") = 3;
387 $var("foo") = "foo indeed";
388 pv_var_to_xavp("temp", "ok");
389 ...
390 $xavp("ok[0]=>temp") now is 3
391 ...
392 pv_var_to_xavp("*", "ok");
393 ...
394 $xavp("ok[0]=>temp") now is 3
395 $xavp("ok[0]=>foo") now is "foo indeed"
396 ...
397
398 4.12.  pv_xavp_to_var(xname)
399
400    Copy xavp values into vars. Reverse of pv_var_to_xavp().
401
402    Both parameters can contain variables that are evaluated at runtime.
403
404    Function can be used from ANY_ROUTE.
405
406    Example 1.15. pv_xavp_to_var() usage
407 ...
408 $xavp("bar=>temp") = 3;
409 $xavp("bar[0]=>foo") = "foo indeed";
410 pv_xavp_to_var("bar");
411 ...
412 $var("temp") now is 3
413 $var("foo") now is "foo indeed"
414 ...
415
416 4.13.  pv_evalx(dst, fmt)
417
418    The fmt string is evaluated twice for exiting variables, the result is
419    stored in dst variable. The dst must be the name of a writable
420    variable. The fmt can contain variables that have a value containing
421    other variables.
422
423    Function can be used from ANY_ROUTE.
424
425    Example 1.16. pv_xavp_to_var() usage
426 ...
427 $var(x) = "test";
428 $var(y) = "$var(x)"
429 pv_evalx("$var(z)", "$var(y) one");
430
431 # - the value of $var(z) is "test one"
432 ...
433
434 5. RPC Commands
435
436    5.1. pv.shvSet
437    5.2. pv.shvGet
438
439 5.1. pv.shvSet
440
441    Set the value of a shared variable ($shv(name)).
442
443    Parameters:
444      * _name_: shared variable name
445      * _type_: type of the value
446           + “int”: integer value
447           + “str”: string value
448      * _value_: value to be set
449
450    Example 1.17. pv.shvSet usage
451 ...
452 $ kamcmd pv.shvSet debug int 3
453 ...
454
455 5.2. pv.shvGet
456
457    Get the value of a shared variable ($shv(name)).
458
459    Parameters:
460      * _name_: shared variable name
461
462    If no name is given, all shared variables are listed.
463
464    Example 1.18. pv.shvGet usage
465 ...
466 $ kamcmd pv.shvGet debug
467 ...