pv: docs - updated xavp management functions names
[sip-router] / src / modules / pv / doc / pv_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module User's Guide -->
11
12 <chapter>
13
14         <title>&adminguide;</title>
15
16         <section>
17         <title>Overview</title>
18         <para>
19                 This module collects the core pseudo-variables that can be used in
20                 configuration file. They are listed in wiki: &kamwikilink; 
21                 in Pseudo-Variables section
22         </para>
23         </section>
24         <section>
25         <title>Dependencies</title>
26         <section>
27                 <title>&kamailio; Modules</title>
28                 <para>
29                 The following modules must be loaded before this module:
30                         <itemizedlist>
31                         <listitem>
32                         <para>
33                                 <emphasis>No dependencies on other &kamailio; modules</emphasis>.
34                         </para>
35                         </listitem>
36                         </itemizedlist>
37                 </para>
38         </section>
39         <section>
40                 <title>External Libraries or Applications</title>
41                 <para>
42                 The following libraries or applications must be installed before running
43                 &kamailio; with this module loaded:
44                         <itemizedlist>
45                         <listitem>
46                         <para>
47                                 <emphasis>None</emphasis>.
48                         </para>
49                         </listitem>
50                         </itemizedlist>
51                 </para>
52         </section>
53         </section>
54         <section>
55         <title>Parameters</title>
56         <section id="pv.p.shvset">
57                 <title><varname>shvset</varname> (string)</title>
58                 <para>
59                 Set the value of a shared variable ($shv(name)). The parameter
60                 can be set many times.
61                 </para>
62                 <para>
63                 The value of the parameter has the format:
64                 _name_ '=' _type_ ':' _value_
65                 </para>
66                 <itemizedlist>
67                         <listitem><para>_name_: shared variable name</para></listitem>
68
69                         <listitem><para>_type_: type of the value</para>
70                          <itemizedlist>
71             <listitem><para> <quote>i</quote>: integer value </para></listitem>
72                 <listitem><para> <quote>s</quote>: string value </para></listitem>
73                       </itemizedlist>
74                         </listitem>
75
76                         <listitem><para>_value_: value to be set</para></listitem>
77                 </itemizedlist>
78                 <para>
79                 Default value is <quote>NULL</quote>.
80                 </para>
81                 <example>
82                 <title><varname>shvset</varname> parameter usage</title>
83                 <programlisting format="linespecific">
84 ...
85 modparam("pv", "shvset", "debug=i:1")
86 modparam("pv", "shvset", "pstngw=s:sip:10.10.10.10")
87 ...
88 </programlisting>
89             </example>
90         </section>
91         <section id="pv.p.varset">
92                 <title><varname>varset</varname> (string)</title>
93                 <para>
94                 Set the value of a script variable ($var(name)). The parameter
95                 can be set many times.
96                 </para>
97                 <para>
98                 The value of the parameter has the format:
99                 _name_ '=' _type_ ':' _value_
100                 </para>
101                 <itemizedlist>
102                         <listitem><para>_name_: shared variable name</para></listitem>
103
104                         <listitem><para>_type_: type of the value</para>
105                          <itemizedlist>
106              <listitem><para> <quote>i</quote>: integer value </para></listitem>
107                  <listitem><para> <quote>s</quote>: string value </para></listitem>
108                          </itemizedlist>
109                         </listitem>
110
111                         <listitem><para>_value_: value to be set</para></listitem>
112                 </itemizedlist>
113                 <para>
114                 Default value is <quote>NULL</quote>.
115                 </para>
116                 <example>
117                 <title><varname>varset</varname> parameter usage</title>
118                 <programlisting format="linespecific">
119 ...
120 modparam("pv", "varset", "init=i:1")
121 modparam("pv", "varset", "gw=s:sip:11.11.11.11;transport=tcp")
122 ...
123 </programlisting>
124             </example>
125         </section>
126                 <section id="pv.p.avp_aliases">
127                         <title><varname>avp_aliases</varname> (string)</title>
128                         <para>
129                         Define aliases for PV AVP names.
130                         </para>
131                         <para>
132                                 <emphasis>
133                                         Default value is NULL.
134                                 </emphasis>
135                         </para>
136                         <example>
137                                 <title><varname>avp_aliases</varname> parameter usage</title>
138                                 <programlisting format="linespecific">
139 ...
140 modparam("pv","avp_aliases","email=s:email_addr;tmp=i:100")
141 ...
142                                 </programlisting>
143                         </example>
144                 </section>
145         </section>
146         <section>
147         <title>Functions</title>
148                 <section id="pv.f.pv_isset">
149                 <title><function moreinfo="none">pv_isset(pvar)</function></title>
150                 <para>
151                         Return true if a PV value is different than 'null'.
152                 </para>
153                 <para>Meaning of the parameters is as follows:</para>
154                 <itemizedlist>
155                 <listitem>
156                         <para>
157                                 <emphasis>pvar</emphasis> - pvar identifier.
158                         </para>
159                 </listitem>
160                 </itemizedlist>
161                 <para>
162                 This function can be used from ANY_ROUTE.
163                 </para>
164                 <example>
165                 <title><function>pv_isset</function> usage</title>
166                 <programlisting format="linespecific">
167 ...
168 if(pv_isset("$avp(s:x)"))
169 {
170     ...
171 }
172 ...
173 </programlisting>
174                 </example>
175                 </section>
176                 <section id="pv.f.pv_unset">
177                 <title><function moreinfo="none">pv_unset(pvar)</function></title>
178                 <para>
179                         Unset the value of the PV (e.g., delete AVP, set to null).
180                 </para>
181                 <para>Meaning of the parameters is as follows:</para>
182                 <itemizedlist>
183                 <listitem>
184                         <para>
185                                 <emphasis>pvar</emphasis> - pvar identifier.
186                         </para>
187                 </listitem>
188                 </itemizedlist>
189                 <para>
190                 This function can be used from ANY_ROUTE.
191                 </para>
192                 <example>
193                 <title><function>pv_unset</function> usage</title>
194                 <programlisting format="linespecific">
195 ...
196 pv_unset("$avp(s:x)");
197 ...
198 </programlisting>
199                 </example>
200                 </section>
201                 <section id="pv.f.is_int">
202                         <title>
203                                 <function moreinfo="none">is_int(pvar)</function>
204                         </title>
205                         <para>
206                         Function checks if pvar argument contains integer value
207                         and returns 1 if it does and -1 otherwise.
208                         </para>
209                         <para>
210                         Function can be used from all kinds of routes.
211                         </para>
212                         <example>
213                                 <title><function>is_int()</function> usage</title>
214                                 <programlisting format="linespecific">
215 ...
216 if (is_int("$var(foo)")) {
217     xlog("L_INFO", "variable foo contains integer value\n");
218 }
219 ...
220                                 </programlisting>
221                         </example>
222                 </section>
223                 <section id="pv.f.typeof">
224                         <title>
225                                 <function moreinfo="none">typeof(pvar, vtype)</function>
226                         </title>
227                         <para>
228                         Returns true if the type of pseudo-variable matches the second
229                         parameter. The second parameter can be: 'int' - type is integer;
230                         'str' - type is string; 'null' - type is null.
231                         </para>
232                         <para>
233                         Function can be used from ANYROUTE.
234                         </para>
235                         <example>
236                                 <title><function>typeof()</function> usage</title>
237                                 <programlisting format="linespecific">
238 ...
239 if (typeof("$var(foo)", "str")) {
240     xdbg("variable foo is a string\n");
241 }
242 ...
243                                 </programlisting>
244                         </example>
245                 </section>
246                 <section id="pv.f.not_empty">
247                         <title>
248                                 <function moreinfo="none">not_empty(pvar)</function>
249                         </title>
250                         <para>
251                         Returns true if the pseudo-variables has the type string and
252                         is not empty value.
253                         </para>
254                         <para>
255                         Function can be used from all kinds of routes.
256                         </para>
257                         <example>
258                                 <title><function>not_empty()</function> usage</title>
259                                 <programlisting format="linespecific">
260 ...
261 if (not_empty("$var(foo)")) {
262     append_hf("X-Foo: $var(foo)\r\n");
263 }
264 ...
265                                 </programlisting>
266                         </example>
267                 </section>
268                 <section id="pv.f.xavp_params_explode">
269                         <title>
270                                 <function moreinfo="none">xavp_params_explode(sparams, xname)</function>
271                         </title>
272                         <para>
273                                 Convert a parameters string in xavp atributes.
274                         </para>
275                         <para>
276                                 The first parameter has to be a string in the format of SIP header
277                                 parameters (name1=value1;...;nameN=valueN). The second parameter
278                                 is the name of the root xavp to hold the pairs (nameX,valueX).
279                         </para>
280                         <para>
281                                 The values are stored as string type.
282                         </para>
283                         <para>
284                         Function can be used from ANY ROUTE.
285                         </para>
286                         <example>
287                                 <title><function>xavp_params_explode</function> usage</title>
288                                 <programlisting format="linespecific">
289 ...
290 xavp_params_explode("a=b;c=d;e=d", "x");
291 # results in:
292 #    $xavp(x=&gt;a) = "b";
293 #    $xavp(x=&gt;c) = "d";
294 #    $xavp(x=&gt;e) = "f";
295 ...
296                                 </programlisting>
297                         </example>
298                 </section>
299                 <section id="pv.f.xavp_params_implode">
300                         <title>
301                                 <function moreinfo="none">xavp_params_implode(xname, pvname)</function>
302                         </title>
303                         <para>
304                                 Serialize the subfields in an XAVP to a parameters string format.
305                         </para>
306                         <para>
307                                 The first parameter has to be the name of XAVP (only the string
308                                 name, not the in $xavp(name)). The second parameter
309                                 is the name of output variable (in full name, like $var(output)).
310                         </para>
311                         <para>
312                                 The value is stored as string type.
313                         </para>
314                         <para>
315                         Function can be used from ANY ROUTE.
316                         </para>
317                         <example>
318                                 <title><function>xavp_params_implode</function> usage</title>
319                                 <programlisting format="linespecific">
320 ...
321 $xavp(x=&gt;e) = "f";
322 $xavp(x[0]=&gt;c) = "d";
323 $xavp(x[0]=&gt;a) = "b";
324 xavp_params_implode("x", "$var(out)");
325 # results in: $var(out) is "a=b;c=d;e=f;"
326 ...
327                                 </programlisting>
328                         </example>
329                 </section>
330                 <section id="pv.f.xavp_child_seti">
331                         <title>
332                                 <function moreinfo="none">xavp_child_seti(rname, cname, ival)</function>
333                         </title>
334                         <para>
335                                 Set the value of $xavp(rname=&gt;cname) to integer value ival.
336                         </para>
337                         <para>
338                                 The first parameter has to be the name of XAVP in the root list.
339                                 The second parameter name of child XAVP. The third parameter
340                                 can be an integer number or a variable holding an integer.
341                         </para>
342                         <para>
343                         Function can be used from ANY ROUTE.
344                         </para>
345                         <example>
346                                 <title><function>xavp_child_seti</function> usage</title>
347                                 <programlisting format="linespecific">
348 ...
349 $var(n) = 10;
350 xavp_child_seti("x", "y", "$var(n)");
351 # results in: $xavp(x=&gt;y) is 10
352 ...
353                                 </programlisting>
354                         </example>
355                 </section>
356                 <section id="pv.f.xavp_child_sets">
357                         <title>
358                                 <function moreinfo="none">xavp_child_sets(rname, cname, sval)</function>
359                         </title>
360                         <para>
361                                 Set the value of $xavp(rname=&gt;cname) to string value sval.
362                         </para>
363                         <para>
364                                 The first parameter has to be the name of XAVP in the root list.
365                                 The second parameter name of child XAVP. The third parameter
366                                 can be a static or dynamic (with variables) string.
367                         </para>
368                         <para>
369                         Function can be used from ANY ROUTE.
370                         </para>
371                         <example>
372                                 <title><function>xavp_child_sets</function> usage</title>
373                                 <programlisting format="linespecific">
374 ...
375 $var(n) = 10;
376 xavp_child_sets("x", "y", "Count: $var(n)");
377 # results in: $xavp(x=&gt;y) is "Count: 10"
378 ...
379                                 </programlisting>
380                         </example>
381                 </section>
382                 <section id="pv.f.xavp_rm">
383                         <title>
384                                 <function moreinfo="none">xavp_rm(rname)</function>
385                         </title>
386                         <para>
387                                 Remove the value of $xavp(rname).
388                         </para>
389                         <para>
390                                 The parameter has to be the name of XAVP in the root list.
391                                 It can be static or dynamic string (to include variables).
392                         </para>
393                         <para>
394                         Function can be used from ANY ROUTE.
395                         </para>
396                         <example>
397                                 <title><function>xavp_rm</function> usage</title>
398                                 <programlisting format="linespecific">
399 ...
400 xavp_rm("x");
401 # same result as: $xavp(x) = $null;
402 ...
403                                 </programlisting>
404                         </example>
405                 </section>
406
407                 <section id="pv.f.xavp_child_rm">
408                         <title>
409                                 <function moreinfo="none">xavp_child_rm(rname, cname)</function>
410                         </title>
411                         <para>
412                                 Remove the value of $xavp(rname=&gt;cname).
413                         </para>
414                         <para>
415                                 The first parameter has to be the name of XAVP in the root list.
416                                 The second parameter name of child XAVP. Both parameters can be
417                                 static or dynamic strings (to include variables).
418                         </para>
419                         <para>
420                         Function can be used from ANY ROUTE.
421                         </para>
422                         <example>
423                                 <title><function>xavp_child_rm</function> usage</title>
424                                 <programlisting format="linespecific">
425 ...
426 xavp_child_rm("x", "y");
427 # same result as: $xavp(x=&gt;y) = $null;
428 ...
429                                 </programlisting>
430                         </example>
431                 </section>
432                 <section id="pv.f.sbranch_set_ruri">
433                         <title>
434                                 <function moreinfo="none">sbranch_set_ruri()</function>
435                         </title>
436                         <para>
437                                 Use the attributes from static branch ($sbranch(key) variable) to
438                                 set request URI and the other fields of the branch associated with
439                                 request URI (destination URI, path, ...).
440                         </para>
441                         <para>
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                         </para>
445                         <para>
446                         Function can be used from REQUEST_ROUTE, BRANCH_ROUTE or FAILURE_ROUTE.
447                         </para>
448                         <example>
449                                 <title><function>sbranch_set_ruri()</function> usage</title>
450                                 <programlisting format="linespecific">
451 ...
452 sbranch_reset();
453 $sbranch(uri) = "sip:127.0.0.1:5080";
454 $sbranch(dst_uri) =  "sip:127.0.0.1:5090";
455 $sbranch(path) =  "sip:127.0.0.1:5090, sip:127.0.0.1:5094";
456 $sbranch(send_socket) =  "udp:127.0.0.1:5060";
457 sbranch_set_ruri();
458 ...
459                                 </programlisting>
460                         </example>
461                 </section>
462                 <section id="pv.f.sbranch_append">
463                         <title>
464                                 <function moreinfo="none">sbranch_append()</function>
465                         </title>
466                         <para>
467                                 Use the attributes from static branch ($sbranch(key) variable) to
468                                 append a new branch to destination set. It is an alternative to
469                                 append_branch() that allows setting each attribute specific to
470                                 the branch.
471                         </para>
472                         <para>
473                                 Content of the static branch is not reset after this function is
474                                 executed. It has to be done explicitly with sbranch_reset().
475                         </para>
476                         <para>
477                         Function can be used from REQUEST_ROUTE, BRANCH_ROUTE or FAILURE_ROUTE.
478                         </para>
479                         <example>
480                                 <title><function>sbranch_append()</function> usage</title>
481                                 <programlisting format="linespecific">
482 ...
483 sbranch_reset();
484 $sbranch(uri) = "sip:127.0.0.1:5080";
485 $sbranch(dst_uri) =  "sip:127.0.0.1:5090";
486 $sbranch(send_socket) =  "udp:127.0.0.1:5060";
487 sbranch_append();
488 ...
489                                 </programlisting>
490                         </example>
491                 </section>
492                 <section id="pv.f.sbranch_reset">
493                         <title>
494                                 <function moreinfo="none">sbranch_reset()</function>
495                         </title>
496                         <para>
497                                 Reset the content of static branch ($sbranch(key) variable.
498                         </para>
499                         <para>
500                         Function can be used from REQUEST_ROUTE, BRANCH_ROUTE or FAILURE_ROUTE.
501                         </para>
502                         <example>
503                                 <title><function>sbranch_append()</function> usage</title>
504                                 <programlisting format="linespecific">
505 ...
506 sbranch_reset();
507 ...
508                                 </programlisting>
509                         </example>
510                 </section>
511                 <section id="pv.f.pv_xavp_print">
512                         <title>
513                                 <function moreinfo="none">pv_xavp_print()</function>
514                         </title>
515                         <para>
516                                 Print all XAVPs to the syslog using INFO log level.
517                         </para>
518                         <para>
519                         Function can be used from ANY_ROUTE.
520                         </para>
521                         <example>
522                                 <title><function>pv_xavp_print()</function> usage</title>
523                                 <programlisting format="linespecific">
524 ...
525 pv_xavp_print();
526 ...
527                                 </programlisting>
528                         </example>
529                 </section>
530                 <section id="pv.f.pv_var_to_xavp">
531                         <title>
532                                 <function moreinfo="none">pv_var_to_xavp(varname, xname)</function>
533                         </title>
534                         <para>
535                                 Copy the script variable value into an xavp.
536                         </para>
537                         <para>
538                                 First parameter can be '*' in order to copy all script variables.
539                                 Second parameter is the name of the destination xavp.
540                                 If xavp already exists it will be reset first.
541                         </para>
542                         <para>
543                                 Both parameters can contain variables that are evaluated at
544                                 runtime.
545                         </para>
546                         <para>
547                         Function can be used from ANY_ROUTE.
548                         </para>
549                         <example>
550                                 <title><function>pv_var_to_xavp()</function> usage</title>
551                                 <programlisting format="linespecific">
552 ...
553 $var("temp") = 3;
554 $var("foo") = "foo indeed";
555 pv_var_to_xavp("temp", "ok");
556 ...
557 $xavp("ok[0]=>temp") now is 3
558 ...
559 pv_var_to_xavp("*", "ok");
560 ...
561 $xavp("ok[0]=>temp") now is 3
562 $xavp("ok[0]=>foo") now is "foo indeed"
563 ...
564                                 </programlisting>
565                         </example>
566                 </section>
567                 <section id="pv.f.pv_xavp_to_var">
568                         <title>
569                                 <function moreinfo="none">pv_xavp_to_var(xname)</function>
570                         </title>
571                         <para>
572                                 Copy xavp values into vars. Reverse of pv_var_to_xavp().
573                         </para>
574                         <para>
575                                 Both parameters can contain variables that are evaluated at
576                                 runtime.
577                         </para>
578                         <para>
579                         Function can be used from ANY_ROUTE.
580                         </para>
581                         <example>
582                                 <title><function>pv_xavp_to_var()</function> usage</title>
583                                 <programlisting format="linespecific">
584 ...
585 $xavp("bar=>temp") = 3;
586 $xavp("bar[0]=>foo") = "foo indeed";
587 pv_xavp_to_var("bar");
588 ...
589 $var("temp") now is 3
590 $var("foo") now is "foo indeed"
591 ...
592                                 </programlisting>
593                         </example>
594                 </section>
595                 <section id="pv.f.pv_evalx">
596                         <title>
597                                 <function moreinfo="none">pv_evalx(dst, fmt)</function>
598                         </title>
599                         <para>
600                                 The fmt string is evaluated twice for exiting variables,
601                                 the result is stored in dst variable. The dst must be the
602                                 name of a writable variable. The fmt can contain variables
603                                 that have a value containing other variables.
604                         </para>
605
606                         <para>
607                         Function can be used from ANY_ROUTE.
608                         </para>
609                         <example>
610                                 <title><function>pv_xavp_to_var()</function> usage</title>
611                                 <programlisting format="linespecific">
612 ...
613 $var(x) = "test";
614 $var(y) = "$var(x)"
615 pv_evalx("$var(z)", "$var(y) one");
616
617 # - the value of $var(z) is "test one"
618 ...
619                                 </programlisting>
620                         </example>
621                 </section>
622         </section>
623
624         <section>
625         <title>RPC Commands</title>
626                 <section id="pv.rpc.shvSet">
627                         <title><function moreinfo="none">pv.shvSet</function></title>
628                         <para>
629                                 Set the value of a shared variable ($shv(name)).
630                         </para>
631                 <para>Parameters:</para>
632                 <itemizedlist>
633                         <listitem><para>_name_: shared variable name</para></listitem>
634
635                         <listitem><para>_type_: type of the value</para>
636                               <itemizedlist>
637             <listitem><para> <quote>int</quote>: integer value </para></listitem>
638                 <listitem><para> <quote>str</quote>: string value </para></listitem>
639                                   </itemizedlist>
640                         </listitem>
641
642                         <listitem><para>_value_: value to be set</para></listitem>
643                 </itemizedlist>
644                         <example>
645                         <title><function moreinfo="none">pv.shvSet</function> usage</title>
646                         <programlisting format="linespecific">
647 ...
648 $ &kamcmd; pv.shvSet debug int 3
649 ...
650 </programlisting>
651                         </example>
652                 </section>
653                 <section id="pv.rpc.shvGet">
654                         <title><function moreinfo="none">pv.shvGet</function></title>
655                         <para>
656                                 Get the value of a shared variable ($shv(name)).
657                         </para>
658                 <para>Parameters:</para>
659                 <itemizedlist>
660                         <listitem><para>_name_: shared variable name</para></listitem>
661                 </itemizedlist>
662                 <para>If no name is given, all shared variables are listed.</para>
663                         <example>
664                         <title><function moreinfo="none">pv.shvGet</function> usage</title>
665                         <programlisting format="linespecific">
666 ...
667 $ &kamcmd; pv.shvGet debug
668 ...
669 </programlisting>
670                         </example>
671
672                 </section>
673         </section>
674
675 </chapter>
676