Pseudo-Variables Module

Daniel-Constantin Mierla

   asipto.com
   <daniel@asipto.com>

Edited by

Daniel-Constantin Mierla

   <daniel@asipto.com>

   Copyright © 2008-2011 Daniel-Constantin Mierla (asipto.com)

   Copyright © 2011 Juha Heinanen

   Copyright © 2013 Olle E. Johansson, Edvina AB
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. shvset (string)
              3.2. varset (string)
              3.3. avp_aliases (string)

        4. Functions

              4.1. pv_isset(pvar)
              4.2. pv_unset(pvar)
              4.3. is_int(pvar)
              4.4. typeof(pvar, vtype)
              4.5. not_empty(pvar)
              4.6. xavp_copy(source_name, source_index, destination_name)
              4.7. xavp_copy(source_name, source_index, destination_name,
                      destination_index)

              4.8. xavp_params_explode(sparams, xname)
              4.9. xavp_params_implode(xname, pvname)
              4.10. xavp_slist_explode(slist, sep, mode, xname)
              4.11. xavp_child_seti(rname, cname, ival)
              4.12. xavi_child_seti(rname, cname, ival)
              4.13. xavp_child_sets(rname, cname, sval)
              4.14. xavi_child_sets(rname, cname, sval)
              4.15. xavp_rm(rname)
              4.16. xavi_rm(rname)
              4.17. xavp_child_rm(rname, cname)
              4.18. xavi_child_rm(rname, cname)
              4.19. sbranch_set_ruri()
              4.20. sbranch_append()
              4.21. sbranch_reset()
              4.22. pv_xavp_print()
              4.23. pv_xavu_print()
              4.24. pv_xavi_print()
              4.25. pv_var_to_xavp(varname, xname)
              4.26. pv_xavp_to_var(xname)
              4.27. pv_evalx(dst, fmt)

        5. RPC Commands

              5.1. pv.shvSet
              5.2. pv.shvGet

   List of Examples

   1.1. shvset parameter usage
   1.2. varset parameter usage
   1.3. avp_aliases parameter usage
   1.4. pv_isset usage
   1.5. pv_unset usage
   1.6. is_int() usage
   1.7. typeof() usage
   1.8. not_empty() usage
   1.9. xavp_copy usage
   1.10. xavp_copy usage
   1.11. xavp_params_explode usage
   1.12. xavp_params_implode usage
   1.13. xavp_slist_explode usage
   1.14. xavp_child_seti usage
   1.15. xavi_child_seti usage
   1.16. xavp_child_sets usage
   1.17. xavi_child_sets usage
   1.18. xavp_rm usage
   1.19. xavi_rm usage
   1.20. xavp_child_rm usage
   1.21. xavi_child_rm usage
   1.22. sbranch_set_ruri() usage
   1.23. sbranch_append() usage
   1.24. sbranch_append() usage
   1.25. pv_xavp_print() usage
   1.26. pv_xavu_print() usage
   1.27. pv_xavi_print() usage
   1.28. pv_var_to_xavp() usage
   1.29. pv_xavp_to_var() usage
   1.30. pv_xavp_to_var() usage
   1.31. pv.shvSet usage
   1.32. pv.shvGet usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Parameters

        3.1. shvset (string)
        3.2. varset (string)
        3.3. avp_aliases (string)

   4. Functions

        4.1. pv_isset(pvar)
        4.2. pv_unset(pvar)
        4.3. is_int(pvar)
        4.4. typeof(pvar, vtype)
        4.5. not_empty(pvar)
        4.6. xavp_copy(source_name, source_index, destination_name)
        4.7. xavp_copy(source_name, source_index, destination_name,
                destination_index)

        4.8. xavp_params_explode(sparams, xname)
        4.9. xavp_params_implode(xname, pvname)
        4.10. xavp_slist_explode(slist, sep, mode, xname)
        4.11. xavp_child_seti(rname, cname, ival)
        4.12. xavi_child_seti(rname, cname, ival)
        4.13. xavp_child_sets(rname, cname, sval)
        4.14. xavi_child_sets(rname, cname, sval)
        4.15. xavp_rm(rname)
        4.16. xavi_rm(rname)
        4.17. xavp_child_rm(rname, cname)
        4.18. xavi_child_rm(rname, cname)
        4.19. sbranch_set_ruri()
        4.20. sbranch_append()
        4.21. sbranch_reset()
        4.22. pv_xavp_print()
        4.23. pv_xavu_print()
        4.24. pv_xavi_print()
        4.25. pv_var_to_xavp(varname, xname)
        4.26. pv_xavp_to_var(xname)
        4.27. pv_evalx(dst, fmt)

   5. RPC Commands

        5.1. pv.shvSet
        5.2. pv.shvGet

1. Overview

   This module collects the core pseudo-variables that can be used in
   configuration file. They are listed in wiki:
   https://www.kamailio.org/wiki/ in Pseudo-Variables section

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   The following modules must be loaded before this module:
     * No dependencies on other Kamailio modules.

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * None.

3. Parameters

   3.1. shvset (string)
   3.2. varset (string)
   3.3. avp_aliases (string)

3.1. shvset (string)

   Set the initial value of a shared variable ($shv(name)). The parameter
   can be set many times.

   The value of the parameter has the format: _name_ '=' _type_ ':'
   _value_
     * _name_: shared variable name
     * _type_: type of the value
          + “i”: integer value
          + “s”: string value
     * _value_: value to be set

   Note: this is special useful for usage with KEMI scripts, the $shv(...)
   variables must be defined during Kamailio initialization in order to
   become available in all worker processes.

   Default value is “NULL”.

   Example 1.1. shvset parameter usage
...
modparam("pv", "shvset", "debug=i:1")
modparam("pv", "shvset", "pstngw=s:sip:10.10.10.10")
...

3.2. varset (string)

   Set the value of a script variable ($var(name)). The parameter can be
   set many times.

   The value of the parameter has the format: _name_ '=' _type_ ':'
   _value_
     * _name_: shared variable name
     * _type_: type of the value
          + “i”: integer value
          + “s”: string value
     * _value_: value to be set

   Default value is “NULL”.

   Example 1.2. varset parameter usage
...
modparam("pv", "varset", "init=i:1")
modparam("pv", "varset", "gw=s:sip:11.11.11.11;transport=tcp")
...

3.3. avp_aliases (string)

   Define aliases for PV AVP names.

   Default value is NULL.

   Example 1.3. avp_aliases parameter usage
...
modparam("pv","avp_aliases","email=s:email_addr;tmp=i:100")
...

4. Functions

   4.1. pv_isset(pvar)
   4.2. pv_unset(pvar)
   4.3. is_int(pvar)
   4.4. typeof(pvar, vtype)
   4.5. not_empty(pvar)
   4.6. xavp_copy(source_name, source_index, destination_name)
   4.7. xavp_copy(source_name, source_index, destination_name,
          destination_index)

   4.8. xavp_params_explode(sparams, xname)
   4.9. xavp_params_implode(xname, pvname)
   4.10. xavp_slist_explode(slist, sep, mode, xname)
   4.11. xavp_child_seti(rname, cname, ival)
   4.12. xavi_child_seti(rname, cname, ival)
   4.13. xavp_child_sets(rname, cname, sval)
   4.14. xavi_child_sets(rname, cname, sval)
   4.15. xavp_rm(rname)
   4.16. xavi_rm(rname)
   4.17. xavp_child_rm(rname, cname)
   4.18. xavi_child_rm(rname, cname)
   4.19. sbranch_set_ruri()
   4.20. sbranch_append()
   4.21. sbranch_reset()
   4.22. pv_xavp_print()
   4.23. pv_xavu_print()
   4.24. pv_xavi_print()
   4.25. pv_var_to_xavp(varname, xname)
   4.26. pv_xavp_to_var(xname)
   4.27. pv_evalx(dst, fmt)

4.1. pv_isset(pvar)

   Return true if a PV value is different than 'null'.

   Meaning of the parameters is as follows:
     * pvar - pvar identifier.

   This function can be used from ANY_ROUTE.

   Example 1.4. pv_isset usage
...
if(pv_isset("$avp(s:x)"))
{
    ...
}
...

4.2. pv_unset(pvar)

   Unset the value of the PV (e.g., delete AVP, set to null).

   Meaning of the parameters is as follows:
     * pvar - pvar identifier.

   This function can be used from ANY_ROUTE.

   Example 1.5. pv_unset usage
...
pv_unset("$avp(s:x)");
...

4.3.  is_int(pvar)

   Function checks if pvar argument contains integer value and returns 1
   if it does and -1 otherwise.

   Function can be used from all kinds of routes.

   Example 1.6. is_int() usage
...
if (is_int("$var(foo)")) {
    xlog("L_INFO", "variable foo contains integer value\n");
}
...

4.4.  typeof(pvar, vtype)

   Returns true if the type of pseudo-variable matches the second
   parameter. The second parameter can be: 'int' - type is integer; 'str'
   - type is string; 'null' - type is null.

   Function can be used from ANYROUTE.

   Example 1.7. typeof() usage
...
if (typeof("$var(foo)", "str")) {
    xdbg("variable foo is a string\n");
}
...

4.5.  not_empty(pvar)

   Returns true if the pseudo-variables has the type string and is not
   empty value.

   Function can be used from all kinds of routes.

   Example 1.8. not_empty() usage
...
if (not_empty("$var(foo)")) {
    append_hf("X-Foo: $var(foo)\r\n");
}
...

4.6.  xavp_copy(source_name, source_index, destination_name)

   Copy and append one XAVP.

   The parameters can be variables or strings. First parameter is the
   source XAVP name. Second parameter is the source XAVP stack index, use
   0 to copy the last assigned XAVP. Third parameter is the destination
   XAVP name, if found the XAVP will be appended else it will be created.

   Function can be used from ANY ROUTE.

   Example 1.9. xavp_copy usage
...
# Using xavp_copy to reorder an existing xavp stack in a new one
$xavp(a=>x) = "a-0-x";
$xavp(a[0]=>y) = "a-0-y";
$xavp(a=>x) = "a-1-x";
$xavp(a[0]=>y) = "a-1-y";
$xavp(a=>x) = "a-2-x";
$xavp(a[0]=>y) = "a-2-y";

xinfo("BEFORE $xavp(a[0]=>x) == [a-2-x] == $xavp(a[0]=>y) == [a-2-y]\n");
xinfo("BEFORE $xavp(a[1]=>x) == [a-1-x] == $xavp(a[1]=>y) == [a-1-y]\n");
xinfo("BEFORE $xavp(a[2]=>x) == [a-0-x] == $xavp(a[2]=>y) == [a-0-y]\n");

# reorder
$var(source_index) = 1;
$var(destination_name) = "b";
xavp_copy("a", "2", "b");
xavp_copy("a", "$var(source_index)", "$var(destination_name)");
xavp_copy("a", "0", "$var(destination_name)");

xinfo("AFTER $xavp(b[0]=>x) == [a-0-x] == $xavp(b[0]=>y) == [a-0-y]\n");
xinfo("AFTER $xavp(b[1]=>x) == [a-1-x] == $xavp(b[1]=>y) == [a-1-y]\n");
xinfo("AFTER $xavp(b[2]=>x) == [a-2-x] == $xavp(b[2]=>y) == [a-2-y]\n");
...

4.7.  xavp_copy(source_name, source_index, destination_name,
destination_index)

   Copy and replace one XAVP.

   The parameters can be variables or strings. First parameter is the
   source XAVP name. Second parameter is the source XAVP stack index, use
   0 to copy the last assigned XAVP. Third parameter is the destination
   XAVP name, if not found xavp_copy will return -1. Fourth parameter is
   the destination XAVP index, if not found xavp_copy will return -1.

   Function can be used from ANY ROUTE.

   Example 1.10. xavp_copy usage
...
# Using xavp_copy to reorder an existing xavp stack inplace
$xavp(d=>x) = "d-0-x";
$xavp(d[0]=>y) = "d-0-y";
$xavp(d=>x) = "d-1-x";
$xavp(d[0]=>y) = "d-1-y";
$xavp(d=>x) = "d-2-x";
$xavp(d[0]=>y) = "d-2-y";

xinfo("NEW $xavp(d[0]=>x) == [d-2-x] and $xavp(d[0]=>y) == [d-2-y]\n");
xinfo("NEW $xavp(d[1]=>x) == [d-1-x] and $xavp(d[1]=>y) == [d-1-y]\n");
xinfo("NEW $xavp(d[2]=>x) == [d-0-x] and $xavp(d[2]=>y) == [d-0-y]\n");

xavp_copy("d", "0", "e");
xavp_copy("d", "2", "d", "0");
xavp_copy("e", "0", "d", "2");

xinfo("AFTER $xavp(d[0]=>x) == [d-0-x] $xavp(d[0]=>y) == [d-0-y]\n");
xinfo("AFTER $xavp(d[1]=>x) == [d-1-x] $xavp(d[1]=>y) == [d-1-y]\n");
xinfo("AFTER $xavp(d[2]=>x) == [d-2-x] $xavp(d[2]=>y) == [d-2-y]\n");
...

4.8.  xavp_params_explode(sparams, xname)

   Convert a parameters string in xavp atributes.

   The first parameter has to be a string in the format of SIP header
   parameters (name1=value1;...;nameN=valueN). The second parameter is the
   name of the root xavp to hold the pairs (nameX,valueX).

   The values are stored as string type.

   Function can be used from ANY ROUTE.

   Example 1.11. xavp_params_explode usage
...
xavp_params_explode("a=b;c=d;e=d", "x");
# results in:
#    $xavp(x=>a) = "b";
#    $xavp(x=>c) = "d";
#    $xavp(x=>e) = "f";
...

4.9.  xavp_params_implode(xname, pvname)

   Serialize the subfields in an XAVP to a parameters string format.

   The first parameter has to be the name of XAVP (only the string name,
   not the in $xavp(name)). The second parameter is the name of output
   variable (in full name, like $var(output)).

   The value is stored as string type.

   Function can be used from ANY ROUTE.

   Example 1.12. xavp_params_implode usage
...
$xavp(x=>e) = "f";
$xavp(x[0]=>c) = "d";
$xavp(x[0]=>a) = "b";
xavp_params_implode("x", "$var(out)");
# results in: $var(out) is "a=b;c=d;e=f;"
...

4.10.  xavp_slist_explode(slist, sep, mode, xname)

   Breaks a string list in tokens by separators and stores them in XAVPs.
   Note that is not storing empty values.

   The first parameter has to be a string (static or with variables).

   The second parameter has to contain separator characters (they can be
   many).

   The third parameter is mode, controlling the behaviour of extracting
   the tokens, the supported mode right now is 't', which trims the white
   spaces around the value.

   The fourth parameter is the name of the root xavp to hold the tokens in
   fields named 'v' and indexed from 0.

   The values are stored as string type.

   Function can be used from ANY ROUTE.

   Example 1.13. xavp_slist_explode usage
...
xavp_slist_explode("a=b; c=d;", "=;", "t", "x");
# results in:
#    $xavp(x[0]=>v[0]) = "a";
#    $xavp(x[0]=>v[1]) = "b";
#    $xavp(x[0]=>v[2]) = "c";
#    $xavp(x[0]=>v[3]) = "d";
...

4.11.  xavp_child_seti(rname, cname, ival)

   Set the value of $xavp(rname=>cname) to integer value ival.

   The first parameter has to be the name of XAVP in the root list. The
   second parameter name of child XAVP. The third parameter can be an
   integer number or a variable holding an integer.

   Function can be used from ANY ROUTE.

   Example 1.14. xavp_child_seti usage
...
$var(n) = 10;
xavp_child_seti("x", "y", "$var(n)");
# results in: $xavp(x=>y) is 10
...

4.12.  xavi_child_seti(rname, cname, ival)

   Set the value of $xavi(rname=>cname) to integer value ival.

   The first parameter has to be the name of XAVI in the root list. The
   second parameter name of child XAVI. The third parameter can be an
   integer number or a variable holding an integer.

   Function can be used from ANY ROUTE.

   Example 1.15. xavi_child_seti usage
...
$var(n) = 10;
xavi_child_seti("WhatEver", "FoO", "$var(n)");
# results in: $xavi(whatever=>foo) is 10
...

4.13.  xavp_child_sets(rname, cname, sval)

   Set the value of $xavp(rname=>cname) to string value sval.

   The first parameter has to be the name of XAVP in the root list. The
   second parameter name of child XAVP. The third parameter can be a
   static or dynamic (with variables) string.

   Function can be used from ANY ROUTE.

   Example 1.16. xavp_child_sets usage
...
$var(n) = 10;
xavp_child_sets("x", "y", "Count: $var(n)");
# results in: $xavp(x=>y) is "Count: 10"
...

4.14.  xavi_child_sets(rname, cname, sval)

   Set the value of $xavi(rname=>cname) to string value sval.

   The first parameter has to be the name of XAVI in the root list. The
   second parameter name of child XAVI. The third parameter can be a
   static or dynamic (with variables) string.

   Function can be used from ANY ROUTE.

   Example 1.17. xavi_child_sets usage
...
$var(n) = 10;
xavi_child_sets("WhatEver", "FoO", "Count: $var(n)");
# results in: $xavi(whatever=>foo) is "Count: 10"
...

4.15.  xavp_rm(rname)

   Remove the value of $xavp(rname).

   The parameter has to be the name of XAVP in the root list. It can be
   static or dynamic string (to include variables).

   Function can be used from ANY ROUTE.

   Example 1.18. xavp_rm usage
...
xavp_rm("x");
# same result as: $xavp(x) = $null;
...

4.16.  xavi_rm(rname)

   Remove the value of $xavi(rname).

   The parameter has to be the name of XAVI in the root list. It can be
   static or dynamic string (to include variables).

   Function can be used from ANY ROUTE.

   Example 1.19. xavi_rm usage
...
xavi_rm("WhatEver");
# same result as: $xavi(whatever) = $null;
...

4.17.  xavp_child_rm(rname, cname)

   Remove the value of $xavp(rname=>cname).

   The first parameter has to be the name of XAVP in the root list. The
   second parameter name of child XAVP. Both parameters can be static or
   dynamic strings (to include variables).

   Function can be used from ANY ROUTE.

   Example 1.20. xavp_child_rm usage
...
xavp_child_rm("x", "y");
# same result as: $xavp(x=>y) = $null;
...

4.18.  xavi_child_rm(rname, cname)

   Remove the value of $xavi(rname=>cname).

   The first parameter has to be the name of XAVI in the root list. The
   second parameter name of child XAVI. Both parameters can be static or
   dynamic strings (to include variables).

   Function can be used from ANY ROUTE.

   Example 1.21. xavi_child_rm usage
...
xavi_child_rm("WhatEver", "FoO");
# same result as: $xavi(whatever=>foo) = $null;
...

4.19.  sbranch_set_ruri()

   Use the attributes from static branch ($sbranch(key) variable) to set
   request URI and the other fields of the branch associated with request
   URI (destination URI, path, ...).

   Content of the static branch is not reset after this function is
   executed. It has to be done explicitly with sbranch_reset().

   Function can be used from REQUEST_ROUTE, BRANCH_ROUTE or FAILURE_ROUTE.

   Example 1.22. sbranch_set_ruri() usage
...
sbranch_reset();
$sbranch(uri) = "sip:127.0.0.1:5080";
$sbranch(dst_uri) =  "sip:127.0.0.1:5090";
$sbranch(path) =  "sip:127.0.0.1:5090, sip:127.0.0.1:5094";
$sbranch(send_socket) =  "udp:127.0.0.1:5060";
sbranch_set_ruri();
...

4.20.  sbranch_append()

   Use the attributes from static branch ($sbranch(key) variable) to
   append a new branch to destination set. It is an alternative to
   append_branch() that allows setting each attribute specific to the
   branch.

   Content of the static branch is not reset after this function is
   executed. It has to be done explicitly with sbranch_reset().

   Function can be used from REQUEST_ROUTE, BRANCH_ROUTE or FAILURE_ROUTE.

   Example 1.23. sbranch_append() usage
...
sbranch_reset();
$sbranch(uri) = "sip:127.0.0.1:5080";
$sbranch(dst_uri) =  "sip:127.0.0.1:5090";
$sbranch(send_socket) =  "udp:127.0.0.1:5060";
sbranch_append();
...

4.21.  sbranch_reset()

   Reset the content of static branch ($sbranch(key) variable.

   Function can be used from REQUEST_ROUTE, BRANCH_ROUTE or FAILURE_ROUTE.

   Example 1.24. sbranch_append() usage
...
sbranch_reset();
...

4.22.  pv_xavp_print()

   Print all XAVPs to the syslog using INFO log level.

   Function can be used from ANY_ROUTE.

   Example 1.25. pv_xavp_print() usage
...
pv_xavp_print();
...

4.23.  pv_xavu_print()

   Print all XAVUs to the syslog using INFO log level.

   Function can be used from ANY_ROUTE.

   Example 1.26. pv_xavu_print() usage
...
pv_xavu_print();
...

4.24.  pv_xavi_print()

   Print all XAVIs to the syslog using INFO log level.

   Function can be used from ANY_ROUTE.

   Example 1.27. pv_xavi_print() usage
...
pv_xavi_print();
...

4.25.  pv_var_to_xavp(varname, xname)

   Copy the script variable value into an xavp.

   First parameter can be '*' in order to copy all script variables.
   Second parameter is the name of the destination xavp. If xavp already
   exists it will be reset first.

   Both parameters can contain variables that are evaluated at runtime.

   Function can be used from ANY_ROUTE.

   Example 1.28. pv_var_to_xavp() usage
...
$var("temp") = 3;
$var("foo") = "foo indeed";
pv_var_to_xavp("temp", "ok");
...
$xavp("ok[0]=>temp") now is 3
...
pv_var_to_xavp("*", "ok");
...
$xavp("ok[0]=>temp") now is 3
$xavp("ok[0]=>foo") now is "foo indeed"
...

4.26.  pv_xavp_to_var(xname)

   Copy xavp values into vars. Reverse of pv_var_to_xavp().

   Both parameters can contain variables that are evaluated at runtime.

   Function can be used from ANY_ROUTE.

   Example 1.29. pv_xavp_to_var() usage
...
$xavp("bar=>temp") = 3;
$xavp("bar[0]=>foo") = "foo indeed";
pv_xavp_to_var("bar");
...
$var("temp") now is 3
$var("foo") now is "foo indeed"
...

4.27.  pv_evalx(dst, fmt)

   The fmt string is evaluated twice for exiting variables, the result is
   stored in dst variable. The dst must be the name of a writable
   variable. The fmt can contain variables that have a value containing
   other variables.

   Function can be used from ANY_ROUTE.

   Example 1.30. pv_xavp_to_var() usage
...
$var(x) = "test";
$var(y) = "$var(x)"
pv_evalx("$var(z)", "$var(y) one");

# - the value of $var(z) is "test one"
...

5. RPC Commands

   5.1. pv.shvSet
   5.2. pv.shvGet

5.1. pv.shvSet

   Set the value of a shared variable ($shv(name)).

   Parameters:
     * _name_: shared variable name
     * _type_: type of the value
          + “int”: integer value
          + “str”: string value
     * _value_: value to be set

   Example 1.31. pv.shvSet usage
...
$ kamcmd pv.shvSet debug int 3
...

5.2. pv.shvGet

   Get the value of a shared variable ($shv(name)).

   Parameters:
     * _name_: shared variable name

   If no name is given, all shared variables are listed.

   Example 1.32. pv.shvGet usage
...
$ kamcmd pv.shvGet debug
...