modules: use Docbook tag for Kamailio wiki URL
[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.sbranch_set_ruri">
300                         <title>
301                                 <function moreinfo="none">sbranch_set_ruri()</function>
302                         </title>
303                         <para>
304                                 Use the attributes from static branch ($sbranch(key) variable) to
305                                 set request URI and the other fields of the branch associated with
306                                 request URI (destination URI, path, ...).
307                         </para>
308                         <para>
309                                 Content of the static branch is not reset after this function is
310                                 executed. It has to be done explicitely with sbranch_reset().
311                         </para>
312                         <para>
313                         Function can be used from REQUEST_ROUTE, BRANCH_ROUTE or FAILURE_ROUTE.
314                         </para>
315                         <example>
316                                 <title><function>sbranch_set_ruri()</function> usage</title>
317                                 <programlisting format="linespecific">
318 ...
319 sbranch_reset();
320 $sbranch(uri) = "sip:127.0.0.1:5080";
321 $sbranch(dst_uri) =  "sip:127.0.0.1:5090";
322 $sbranch(path) =  "sip:127.0.0.1:5090, sip:127.0.0.1:5094";
323 $sbranch(send_socket) =  "udp:127.0.0.1:5060";
324 sbranch_set_ruri();
325 ...
326                                 </programlisting>
327                         </example>
328                 </section>
329                 <section id="pv.f.sbranch_append">
330                         <title>
331                                 <function moreinfo="none">sbranch_append()</function>
332                         </title>
333                         <para>
334                                 Use the attributes from static branch ($sbranch(key) variable) to
335                                 append a new branch to destination set. It is an alternative to
336                                 append_branch() that allows setting each attribute specific to
337                                 the branch.
338                         </para>
339                         <para>
340                                 Content of the static branch is not reset after this function is
341                                 executed. It has to be done explicitely with sbranch_reset().
342                         </para>
343                         <para>
344                         Function can be used from REQUEST_ROUTE, BRANCH_ROUTE or FAILURE_ROUTE.
345                         </para>
346                         <example>
347                                 <title><function>sbranch_append()</function> usage</title>
348                                 <programlisting format="linespecific">
349 ...
350 sbranch_reset();
351 $sbranch(uri) = "sip:127.0.0.1:5080";
352 $sbranch(dst_uri) =  "sip:127.0.0.1:5090";
353 $sbranch(send_socket) =  "udp:127.0.0.1:5060";
354 sbranch_append();
355 ...
356                                 </programlisting>
357                         </example>
358                 </section>
359                 <section id="pv.f.sbranch_reset">
360                         <title>
361                                 <function moreinfo="none">sbranch_reset()</function>
362                         </title>
363                         <para>
364                                 Reset the content of static branch ($sbranch(key) variable.
365                         </para>
366                         <para>
367                         Function can be used from REQUEST_ROUTE, BRANCH_ROUTE or FAILURE_ROUTE.
368                         </para>
369                         <example>
370                                 <title><function>sbranch_append()</function> usage</title>
371                                 <programlisting format="linespecific">
372 ...
373 sbranch_reset();
374 ...
375                                 </programlisting>
376                         </example>
377                 </section>
378                 <section id="pv.f.pv_xavp_print">
379                         <title>
380                                 <function moreinfo="none">pv_xavp_print()</function>
381                         </title>
382                         <para>
383                                 Print all XAVPs to the syslog using INFO log level.
384                         </para>
385                         <para>
386                         Function can be used from ANY_ROUTE.
387                         </para>
388                         <example>
389                                 <title><function>pv_xavp_print()</function> usage</title>
390                                 <programlisting format="linespecific">
391 ...
392 pv_xavp_print();
393 ...
394                                 </programlisting>
395                         </example>
396                 </section>
397                 <section id="pv.f.pv_var_to_xavp">
398                         <title>
399                                 <function moreinfo="none">pv_var_to_xavp(varname, xname)</function>
400                         </title>
401                         <para>
402                                 Copy the script variable value into an xavp.
403                         </para>
404                         <para>
405                                 First parameter can be '*' in order to copy all script variables.
406                                 Second parameter is the name of the destination xavp.
407                                 If xavp already exists it will be reset first.
408                         </para>
409                         <para>
410                                 Both parameters can contain variables that are evaluated at
411                                 runtime.
412                         </para>
413                         <para>
414                         Function can be used from ANY_ROUTE.
415                         </para>
416                         <example>
417                                 <title><function>pv_var_to_xavp()</function> usage</title>
418                                 <programlisting format="linespecific">
419 ...
420 $var("temp") = 3;
421 $var("foo") = "foo indeed";
422 pv_var_to_xavp("temp", "ok");
423 ...
424 $xavp("ok[0]=>temp") now is 3
425 ...
426 pv_var_to_xavp("*", "ok");
427 ...
428 $xavp("ok[0]=>temp") now is 3
429 $xavp("ok[0]=>foo") now is "foo indeed"
430 ...
431                                 </programlisting>
432                         </example>
433                 </section>
434                 <section id="pv.f.pv_xavp_to_var">
435                         <title>
436                                 <function moreinfo="none">pv_xavp_to_var(xname)</function>
437                         </title>
438                         <para>
439                                 Copy xavp values into vars. Reverse of pv_var_to_xavp().
440                         </para>
441                         <para>
442                                 Both parameters can contain variables that are evaluated at
443                                 runtime.
444                         </para>
445                         <para>
446                         Function can be used from ANY_ROUTE.
447                         </para>
448                         <example>
449                                 <title><function>pv_xavp_to_var()</function> usage</title>
450                                 <programlisting format="linespecific">
451 ...
452 $xavp("bar=>temp") = 3;
453 $xavp("bar[0]=>foo") = "foo indeed";
454 pv_xavp_to_var("bar");
455 ...
456 $var("temp") now is 3
457 $var("foo") now is "foo indeed"
458 ...
459                                 </programlisting>
460                         </example>
461                 </section>
462                 <section id="pv.f.pv_evalx">
463                         <title>
464                                 <function moreinfo="none">pv_evalx(dst, fmt)</function>
465                         </title>
466                         <para>
467                                 The fmt string is evaluated twice for exiting variables,
468                                 the result is stored in dst variable. The dst must be the
469                                 name of a writable variable. The fmt can contain variables
470                                 that have a value containing other variables.
471                         </para>
472
473                         <para>
474                         Function can be used from ANY_ROUTE.
475                         </para>
476                         <example>
477                                 <title><function>pv_xavp_to_var()</function> usage</title>
478                                 <programlisting format="linespecific">
479 ...
480 $var(x) = "test";
481 $var(y) = "$var(x)"
482 pv_evalx("$var(z)", "$var(y) one");
483
484 # - the value of $var(z) is "test one"
485 ...
486                                 </programlisting>
487                         </example>
488                 </section>
489         </section>
490
491         <section>
492         <title>RPC Commands</title>
493                 <section id="pv.rpc.shvSet">
494                         <title><function moreinfo="none">pv.shvSet</function></title>
495                         <para>
496                                 Set the value of a shared variable ($shv(name)).
497                         </para>
498                 <para>Parameters:</para>
499                 <itemizedlist>
500                         <listitem><para>_name_: shared variable name</para></listitem>
501
502                         <listitem><para>_type_: type of the value</para>
503                               <itemizedlist>
504             <listitem><para> <quote>int</quote>: integer value </para></listitem>
505                 <listitem><para> <quote>str</quote>: string value </para></listitem>
506                                   </itemizedlist>
507                         </listitem>
508
509                         <listitem><para>_value_: value to be set</para></listitem>
510                 </itemizedlist>
511                         <example>
512                         <title><function moreinfo="none">pv.shvSet</function> usage</title>
513                         <programlisting format="linespecific">
514 ...
515 $ &kamcmd; pv.shvSet debug int 3
516 ...
517 </programlisting>
518                         </example>
519                 </section>
520                 <section id="pv.rpc.shvGet">
521                         <title><function moreinfo="none">pv.shvGet</function></title>
522                         <para>
523                                 Get the value of a shared variable ($shv(name)).
524                         </para>
525                 <para>Parameters:</para>
526                 <itemizedlist>
527                         <listitem><para>_name_: shared variable name</para></listitem>
528                 </itemizedlist>
529                 <para>If no name is given, all shared variables are listed.</para>
530                         <example>
531                         <title><function moreinfo="none">pv.shvGet</function> usage</title>
532                         <programlisting format="linespecific">
533 ...
534 $ &kamcmd; pv.shvGet debug
535 ...
536 </programlisting>
537                         </example>
538
539                 </section>
540         </section>
541
542 </chapter>
543