git.sip-router.org Git - sip-router/blob - 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