Pseudo-Variables Module

Daniel-Constantin Mierla

asipto.com

Edited by

Daniel-Constantin Mierla


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_params_implode_qval(xname, pvname)
4.11. xavu_params_explode(sparams, xname)
4.12. xavu_params_implode(xname, pvname)
4.13. xavp_slist_explode(slist, sep, mode, xname)
4.14. xavp_child_seti(rname, cname, ival)
4.15. xavi_child_seti(rname, cname, ival)
4.16. xavp_child_sets(rname, cname, sval)
4.17. xavi_child_sets(rname, cname, sval)
4.18. xavp_rm(rname)
4.19. xavi_rm(rname)
4.20. xavp_child_rm(rname, cname)
4.21. xavi_child_rm(rname, cname)
4.22. xavp_lshift(xname, idx)
4.23. xavp_push_dst(xname)
4.24. sbranch_set_ruri()
4.25. sbranch_append()
4.26. sbranch_reset()
4.27. pv_xavp_print()
4.28. pv_xavu_print()
4.29. pv_xavi_print()
4.30. pv_var_to_xavp(varname, xname)
4.31. pv_xavp_to_var(xname)
4.32. 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_params_implode_qval usage
1.14. xavu_params_explode usage
1.15. xavu_params_implode usage
1.16. xavp_slist_explode usage
1.17. xavp_child_seti usage
1.18. xavi_child_seti usage
1.19. xavp_child_sets usage
1.20. xavi_child_sets usage
1.21. xavp_rm usage
1.22. xavi_rm usage
1.23. xavp_child_rm usage
1.24. xavi_child_rm usage
1.25. xavp_lshift usage
1.26. xavp_push_dst usage
1.27. sbranch_set_ruri() usage
1.28. sbranch_append() usage
1.29. sbranch_append() usage
1.30. pv_xavp_print() usage
1.31. pv_xavu_print() usage
1.32. pv_xavi_print() usage
1.33. pv_var_to_xavp() usage
1.34. pv_xavp_to_var() usage
1.35. pv_xavp_to_var() usage
1.36. pv.shvSet usage
1.37. pv.shvGet usage

Chapter 1. Admin Guide

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/wikidocs/ in Pseudo-Variables section

2. Dependencies

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)

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)

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 attributes.

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.

Number values are serialized as unsigned integer 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_params_implode_qval(xname, pvname)

Serialize the subfields in an XAVP to a parameters string format, enclosing string values in double quotes.

Number values are serialized as unsigned integer 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.13. xavp_params_implode_qval usage

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

4.11.  xavu_params_explode(sparams, xname)

Convert a parameters string in xavu attributes.

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 xavu to hold the pairs (nameX,valueX).

The values are stored as string type.

Function can be used from ANY ROUTE.

Example 1.14. xavu_params_explode usage

...
xavu_params_explode("a=b;c=d;e=d", "x");
# results in:
#    $xavu(x=>a) = "b";
#    $xavu(x=>c) = "d";
#    $xavu(x=>e) = "f";
...

4.12.  xavu_params_implode(xname, pvname)

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

Number values are serialized as unsigned integer string format.

The first parameter has to be the name of XAVU (only the string name, not the in $xavu(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.15. xavu_params_implode usage

...
$xavu(x=>e) = "f";
$xavu(x=>c) = "d";
$xavu(x=>a) = "b";
xavu_params_implode("x", "$var(out)");
# results in: $var(out) is "a=b;c=d;e=f;"
...

4.13.  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.16. 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.14.  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.17. xavp_child_seti usage

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

4.15.  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.18. xavi_child_seti usage

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

4.16.  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.19. xavp_child_sets usage

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

4.17.  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.20. xavi_child_sets usage

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

4.18.  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.21. xavp_rm usage

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

4.19.  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.22. xavi_rm usage

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

4.20.  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.23. xavp_child_rm usage

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

4.21.  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.24. xavi_child_rm usage

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

4.22.  xavp_lshift(xname, idx)

Left shift with rotation of the xavps with name xname so that the one at the index idx becomes the first and the ones before it are at the end of the list.

The first parameter has to be the name of XAVP in the root list.

The second parameter is the index of the XAVP that becomes the first one (if it is greater than the number of XAVPs, modulo operation is done first; if it is negative, it counts from the end of the list).

The parameters can be with variables.

Function can be used from ANY ROUTE.

Example 1.25. xavp_lshift usage

...
$xavp(n) = 10;
$xavp(n) = 20;
$xavp(n) = 30;
xavp_lshift("n", "1");
# results in: $xavp(n) having the list of values 20 30 10
...

4.23.  xavp_push_dst(xname)

Set destination fields from XAVP attributes.

The first parameter has to be the name of XAVP in the root list.

The parameters can be with variables.

The attributes that can be stored in the XAVP fields:

  • uri: SIP URI address to set R-URI

  • dsturi: SIP URI address to set DST-URI

  • socket: listen address to set outgoing socket

Function can be used from REQUEST_ROUTE|BRANCH_ROUTE|FAILURE_ROUTE.

Example 1.26. xavp_push_dst usage

...
$xavp(dst=>uri) = "sip:alice@server.com";
$xavp(dst[0]=>dsturi) = "sip:proxy.com";
$xavp(dst[0]=>socket) = "udp:1.2.3.4:5060";
xavp_push_dst("dst");
...

4.24.  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.27. 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.25.  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.28. 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.26.  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.29. sbranch_append() usage

...
sbranch_reset();
...

4.27.  pv_xavp_print()

Print all XAVPs to the syslog using INFO log level.

Function can be used from ANY_ROUTE.

Example 1.30. pv_xavp_print() usage

...
pv_xavp_print();
...

4.28.  pv_xavu_print()

Print all XAVUs to the syslog using INFO log level.

Function can be used from ANY_ROUTE.

Example 1.31. pv_xavu_print() usage

...
pv_xavu_print();
...

4.29.  pv_xavi_print()

Print all XAVIs to the syslog using INFO log level.

Function can be used from ANY_ROUTE.

Example 1.32. pv_xavi_print() usage

...
pv_xavi_print();
...

4.30.  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.33. 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.31.  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.34. 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.32.  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.35. 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

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.36. 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.37. pv.shvGet usage

...
$ kamcmd pv.shvGet debug
...