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. xavp_params_implode(xname, pvname)
46               4.8. xavp_child_seti(rname, cname, ival)
47               4.9. xavp_child_sets(rname, cname, sval)
48               4.10. xavp_rm(rname)
49               4.11. xavp_child_rm(rname, cname)
50               4.12. sbranch_set_ruri()
51               4.13. sbranch_append()
52               4.14. sbranch_reset()
53               4.15. pv_xavp_print()
54               4.16. pv_var_to_xavp(varname, xname)
55               4.17. pv_xavp_to_var(xname)
56               4.18. pv_evalx(dst, fmt)
57
58         5. RPC Commands
59
60               5.1. pv.shvSet
61               5.2. pv.shvGet
62
63    List of Examples
64
65    1.1. shvset parameter usage
66    1.2. varset parameter usage
67    1.3. avp_aliases parameter usage
68    1.4. pv_isset usage
69    1.5. pv_unset usage
70    1.6. is_int() usage
71    1.7. typeof() usage
72    1.8. not_empty() usage
73    1.9. xavp_params_explode usage
74    1.10. xavp_params_implode usage
75    1.11. xavp_child_seti usage
76    1.12. xavp_child_sets usage
77    1.13. xavp_rm usage
78    1.14. xavp_child_rm usage
79    1.15. sbranch_set_ruri() usage
80    1.16. sbranch_append() usage
81    1.17. sbranch_append() usage
82    1.18. pv_xavp_print() usage
83    1.19. pv_var_to_xavp() usage
84    1.20. pv_xavp_to_var() usage
85    1.21. pv_xavp_to_var() usage
86    1.22. pv.shvSet usage
87    1.23. pv.shvGet usage
88
89 Chapter 1. Admin Guide
90
91    Table of Contents
92
93    1. Overview
94    2. Dependencies
95
96         2.1. Kamailio Modules
97         2.2. External Libraries or Applications
98
99    3. Parameters
100
101         3.1. shvset (string)
102         3.2. varset (string)
103         3.3. avp_aliases (string)
104
105    4. Functions
106
107         4.1. pv_isset(pvar)
108         4.2. pv_unset(pvar)
109         4.3. is_int(pvar)
110         4.4. typeof(pvar, vtype)
111         4.5. not_empty(pvar)
112         4.6. xavp_params_explode(sparams, xname)
113         4.7. xavp_params_implode(xname, pvname)
114         4.8. xavp_child_seti(rname, cname, ival)
115         4.9. xavp_child_sets(rname, cname, sval)
116         4.10. xavp_rm(rname)
117         4.11. xavp_child_rm(rname, cname)
118         4.12. sbranch_set_ruri()
119         4.13. sbranch_append()
120         4.14. sbranch_reset()
121         4.15. pv_xavp_print()
122         4.16. pv_var_to_xavp(varname, xname)
123         4.17. pv_xavp_to_var(xname)
124         4.18. pv_evalx(dst, fmt)
125
126    5. RPC Commands
127
128         5.1. pv.shvSet
129         5.2. pv.shvGet
130
131 1. Overview
132
133    This module collects the core pseudo-variables that can be used in
134    configuration file. They are listed in wiki:
135    https://www.kamailio.org/wiki/ in Pseudo-Variables section
136
137 2. Dependencies
138
139    2.1. Kamailio Modules
140    2.2. External Libraries or Applications
141
142 2.1. Kamailio Modules
143
144    The following modules must be loaded before this module:
145      * No dependencies on other Kamailio modules.
146
147 2.2. External Libraries or Applications
148
149    The following libraries or applications must be installed before
150    running Kamailio with this module loaded:
151      * None.
152
153 3. Parameters
154
155    3.1. shvset (string)
156    3.2. varset (string)
157    3.3. avp_aliases (string)
158
159 3.1. shvset (string)
160
161    Set the value of a shared variable ($shv(name)). The parameter can be
162    set many times.
163
164    The value of the parameter has the format: _name_ '=' _type_ ':'
165    _value_
166      * _name_: shared variable name
167      * _type_: type of the value
168           + “i”: integer value
169           + “s”: string value
170      * _value_: value to be set
171
172    Default value is “NULL”.
173
174    Example 1.1. shvset parameter usage
175 ...
176 modparam("pv", "shvset", "debug=i:1")
177 modparam("pv", "shvset", "pstngw=s:sip:10.10.10.10")
178 ...
179
180 3.2. varset (string)
181
182    Set the value of a script variable ($var(name)). The parameter can be
183    set many times.
184
185    The value of the parameter has the format: _name_ '=' _type_ ':'
186    _value_
187      * _name_: shared variable name
188      * _type_: type of the value
189           + “i”: integer value
190           + “s”: string value
191      * _value_: value to be set
192
193    Default value is “NULL”.
194
195    Example 1.2. varset parameter usage
196 ...
197 modparam("pv", "varset", "init=i:1")
198 modparam("pv", "varset", "gw=s:sip:11.11.11.11;transport=tcp")
199 ...
200
201 3.3. avp_aliases (string)
202
203    Define aliases for PV AVP names.
204
205    Default value is NULL.
206
207    Example 1.3. avp_aliases parameter usage
208 ...
209 modparam("pv","avp_aliases","email=s:email_addr;tmp=i:100")
210 ...
211
212 4. Functions
213
214    4.1. pv_isset(pvar)
215    4.2. pv_unset(pvar)
216    4.3. is_int(pvar)
217    4.4. typeof(pvar, vtype)
218    4.5. not_empty(pvar)
219    4.6. xavp_params_explode(sparams, xname)
220    4.7. xavp_params_implode(xname, pvname)
221    4.8. xavp_child_seti(rname, cname, ival)
222    4.9. xavp_child_sets(rname, cname, sval)
223    4.10. xavp_rm(rname)
224    4.11. xavp_child_rm(rname, cname)
225    4.12. sbranch_set_ruri()
226    4.13. sbranch_append()
227    4.14. sbranch_reset()
228    4.15. pv_xavp_print()
229    4.16. pv_var_to_xavp(varname, xname)
230    4.17. pv_xavp_to_var(xname)
231    4.18. pv_evalx(dst, fmt)
232
233 4.1. pv_isset(pvar)
234
235    Return true if a PV value is different than 'null'.
236
237    Meaning of the parameters is as follows:
238      * pvar - pvar identifier.
239
240    This function can be used from ANY_ROUTE.
241
242    Example 1.4. pv_isset usage
243 ...
244 if(pv_isset("$avp(s:x)"))
245 {
246     ...
247 }
248 ...
249
250 4.2. pv_unset(pvar)
251
252    Unset the value of the PV (e.g., delete AVP, set to null).
253
254    Meaning of the parameters is as follows:
255      * pvar - pvar identifier.
256
257    This function can be used from ANY_ROUTE.
258
259    Example 1.5. pv_unset usage
260 ...
261 pv_unset("$avp(s:x)");
262 ...
263
264 4.3.  is_int(pvar)
265
266    Function checks if pvar argument contains integer value and returns 1
267    if it does and -1 otherwise.
268
269    Function can be used from all kinds of routes.
270
271    Example 1.6. is_int() usage
272 ...
273 if (is_int("$var(foo)")) {
274     xlog("L_INFO", "variable foo contains integer value\n");
275 }
276 ...
277
278 4.4.  typeof(pvar, vtype)
279
280    Returns true if the type of pseudo-variable matches the second
281    parameter. The second parameter can be: 'int' - type is integer; 'str'
282    - type is string; 'null' - type is null.
283
284    Function can be used from ANYROUTE.
285
286    Example 1.7. typeof() usage
287 ...
288 if (typeof("$var(foo)", "str")) {
289     xdbg("variable foo is a string\n");
290 }
291 ...
292
293 4.5.  not_empty(pvar)
294
295    Returns true if the pseudo-variables has the type string and is not
296    empty value.
297
298    Function can be used from all kinds of routes.
299
300    Example 1.8. not_empty() usage
301 ...
302 if (not_empty("$var(foo)")) {
303     append_hf("X-Foo: $var(foo)\r\n");
304 }
305 ...
306
307 4.6.  xavp_params_explode(sparams, xname)
308
309    Convert a parameters string in xavp atributes.
310
311    The first parameter has to be a string in the format of SIP header
312    parameters (name1=value1;...;nameN=valueN). The second parameter is the
313    name of the root xavp to hold the pairs (nameX,valueX).
314
315    The values are stored as string type.
316
317    Function can be used from ANY ROUTE.
318
319    Example 1.9. xavp_params_explode usage
320 ...
321 xavp_params_explode("a=b;c=d;e=d", "x");
322 # results in:
323 #    $xavp(x=>a) = "b";
324 #    $xavp(x=>c) = "d";
325 #    $xavp(x=>e) = "f";
326 ...
327
328 4.7.  xavp_params_implode(xname, pvname)
329
330    Serialize the subfields in an XAVP to a parameters string format.
331
332    The first parameter has to be the name of XAVP (only the string name,
333    not the in $xavp(name)). The second parameter is the name of output
334    variable (in full name, like $var(output)).
335
336    The value is stored as string type.
337
338    Function can be used from ANY ROUTE.
339
340    Example 1.10. xavp_params_implode usage
341 ...
342 $xavp(x=>e) = "f";
343 $xavp(x[0]=>c) = "d";
344 $xavp(x[0]=>a) = "b";
345 xavp_params_implode("x", "$var(out)");
346 # results in: $var(out) is "a=b;c=d;e=f;"
347 ...
348
349 4.8.  xavp_child_seti(rname, cname, ival)
350
351    Set the value of $xavp(rname=>cname) to integer value ival.
352
353    The first parameter has to be the name of XAVP in the root list. The
354    second parameter name of child XAVP. The third parameter can be an
355    integer number or a variable holding an integer.
356
357    Function can be used from ANY ROUTE.
358
359    Example 1.11. xavp_child_seti usage
360 ...
361 $var(n) = 10;
362 xavp_child_seti("x", "y", "$var(n)");
363 # results in: $xavp(x=>y) is 10
364 ...
365
366 4.9.  xavp_child_sets(rname, cname, sval)
367
368    Set the value of $xavp(rname=>cname) to string value sval.
369
370    The first parameter has to be the name of XAVP in the root list. The
371    second parameter name of child XAVP. The third parameter can be a
372    static or dynamic (with variables) string.
373
374    Function can be used from ANY ROUTE.
375
376    Example 1.12. xavp_child_sets usage
377 ...
378 $var(n) = 10;
379 xavp_child_sets("x", "y", "Count: $var(n)");
380 # results in: $xavp(x=>y) is "Count: 10"
381 ...
382
383 4.10.  xavp_rm(rname)
384
385    Remove the value of $xavp(rname).
386
387    The parameter has to be the name of XAVP in the root list. It can be
388    static or dynamic string (to include variables).
389
390    Function can be used from ANY ROUTE.
391
392    Example 1.13. xavp_rm usage
393 ...
394 xavp_rm("x");
395 # same result as: $xavp(x) = $null;
396 ...
397
398 4.11.  xavp_child_rm(rname, cname)
399
400    Remove the value of $xavp(rname=>cname).
401
402    The first parameter has to be the name of XAVP in the root list. The
403    second parameter name of child XAVP. Both parameters can be static or
404    dynamic strings (to include variables).
405
406    Function can be used from ANY ROUTE.
407
408    Example 1.14. xavp_child_rm usage
409 ...
410 xavp_child_rm("x", "y");
411 # same result as: $xavp(x=>y) = $null;
412 ...
413
414 4.12.  sbranch_set_ruri()
415
416    Use the attributes from static branch ($sbranch(key) variable) to set
417    request URI and the other fields of the branch associated with request
418    URI (destination URI, path, ...).
419
420    Content of the static branch is not reset after this function is
421    executed. It has to be done explicitly with sbranch_reset().
422
423    Function can be used from REQUEST_ROUTE, BRANCH_ROUTE or FAILURE_ROUTE.
424
425    Example 1.15. sbranch_set_ruri() usage
426 ...
427 sbranch_reset();
428 $sbranch(uri) = "sip:127.0.0.1:5080";
429 $sbranch(dst_uri) =  "sip:127.0.0.1:5090";
430 $sbranch(path) =  "sip:127.0.0.1:5090, sip:127.0.0.1:5094";
431 $sbranch(send_socket) =  "udp:127.0.0.1:5060";
432 sbranch_set_ruri();
433 ...
434
435 4.13.  sbranch_append()
436
437    Use the attributes from static branch ($sbranch(key) variable) to
438    append a new branch to destination set. It is an alternative to
439    append_branch() that allows setting each attribute specific to the
440    branch.
441
442    Content of the static branch is not reset after this function is
443    executed. It has to be done explicitly with sbranch_reset().
444
445    Function can be used from REQUEST_ROUTE, BRANCH_ROUTE or FAILURE_ROUTE.
446
447    Example 1.16. sbranch_append() usage
448 ...
449 sbranch_reset();
450 $sbranch(uri) = "sip:127.0.0.1:5080";
451 $sbranch(dst_uri) =  "sip:127.0.0.1:5090";
452 $sbranch(send_socket) =  "udp:127.0.0.1:5060";
453 sbranch_append();
454 ...
455
456 4.14.  sbranch_reset()
457
458    Reset the content of static branch ($sbranch(key) variable.
459
460    Function can be used from REQUEST_ROUTE, BRANCH_ROUTE or FAILURE_ROUTE.
461
462    Example 1.17. sbranch_append() usage
463 ...
464 sbranch_reset();
465 ...
466
467 4.15.  pv_xavp_print()
468
469    Print all XAVPs to the syslog using INFO log level.
470
471    Function can be used from ANY_ROUTE.
472
473    Example 1.18. pv_xavp_print() usage
474 ...
475 pv_xavp_print();
476 ...
477
478 4.16.  pv_var_to_xavp(varname, xname)
479
480    Copy the script variable value into an xavp.
481
482    First parameter can be '*' in order to copy all script variables.
483    Second parameter is the name of the destination xavp. If xavp already
484    exists it will be reset first.
485
486    Both parameters can contain variables that are evaluated at runtime.
487
488    Function can be used from ANY_ROUTE.
489
490    Example 1.19. pv_var_to_xavp() usage
491 ...
492 $var("temp") = 3;
493 $var("foo") = "foo indeed";
494 pv_var_to_xavp("temp", "ok");
495 ...
496 $xavp("ok[0]=>temp") now is 3
497 ...
498 pv_var_to_xavp("*", "ok");
499 ...
500 $xavp("ok[0]=>temp") now is 3
501 $xavp("ok[0]=>foo") now is "foo indeed"
502 ...
503
504 4.17.  pv_xavp_to_var(xname)
505
506    Copy xavp values into vars. Reverse of pv_var_to_xavp().
507
508    Both parameters can contain variables that are evaluated at runtime.
509
510    Function can be used from ANY_ROUTE.
511
512    Example 1.20. pv_xavp_to_var() usage
513 ...
514 $xavp("bar=>temp") = 3;
515 $xavp("bar[0]=>foo") = "foo indeed";
516 pv_xavp_to_var("bar");
517 ...
518 $var("temp") now is 3
519 $var("foo") now is "foo indeed"
520 ...
521
522 4.18.  pv_evalx(dst, fmt)
523
524    The fmt string is evaluated twice for exiting variables, the result is
525    stored in dst variable. The dst must be the name of a writable
526    variable. The fmt can contain variables that have a value containing
527    other variables.
528
529    Function can be used from ANY_ROUTE.
530
531    Example 1.21. pv_xavp_to_var() usage
532 ...
533 $var(x) = "test";
534 $var(y) = "$var(x)"
535 pv_evalx("$var(z)", "$var(y) one");
536
537 # - the value of $var(z) is "test one"
538 ...
539
540 5. RPC Commands
541
542    5.1. pv.shvSet
543    5.2. pv.shvGet
544
545 5.1. pv.shvSet
546
547    Set the value of a shared variable ($shv(name)).
548
549    Parameters:
550      * _name_: shared variable name
551      * _type_: type of the value
552           + “int”: integer value
553           + “str”: string value
554      * _value_: value to be set
555
556    Example 1.22. pv.shvSet usage
557 ...
558 $ kamcmd pv.shvSet debug int 3
559 ...
560
561 5.2. pv.shvGet
562
563    Get the value of a shared variable ($shv(name)).
564
565    Parameters:
566      * _name_: shared variable name
567
568    If no name is given, all shared variables are listed.
569
570    Example 1.23. pv.shvGet usage
571 ...
572 $ kamcmd pv.shvGet debug
573 ...