Copyright © 2008-2011 Daniel-Constantin Mierla (asipto.com)
Copyright © 2011 Juha Heinanen
Copyright © 2013 Olle E. Johansson, Edvina AB
Table of Contents
pv_isset(pvar)
pv_unset(pvar)
is_int(pvar)
typeof(pvar, vtype)
not_empty(pvar)
xavp_copy(source_name, source_index, destination_name)
xavp_copy(source_name, source_index, destination_name, destination_index)
xavp_params_explode(sparams, xname)
xavp_xparams_explode(sparams, sep, xname)
xavp_params_implode(xname, pvname)
xavp_params_implode_qval(xname, pvname)
xavu_params_explode(sparams, xname)
xavu_params_implode(xname, pvname)
xavp_slist_explode(slist, sep, mode, xname)
xavp_child_seti(rname, cname, ival)
xavi_child_seti(rname, cname, ival)
xavp_child_sets(rname, cname, sval)
xavi_child_sets(rname, cname, sval)
xavp_rm(rname)
xavi_rm(rname)
xavp_child_rm(rname, cname)
xavi_child_rm(rname, cname)
xavp_lshift(xname, idx)
xavp_push_dst(xname)
sbranch_set_ruri()
sbranch_append()
sbranch_reset()
pv_xavp_print()
pv_xavu_print()
pv_xavi_print()
pv_var_to_xavp(varname, xname)
pv_xavp_to_var(xname)
pv_evalx(dst, fmt)
List of Examples
shvset
parameter usagevarset
parameter usageavp_aliases
parameter usagepv_isset
usagepv_unset
usageis_int()
usagetypeof()
usagenot_empty()
usagexavp_copy
usagexavp_copy
usagexavp_params_explode
usagexavp_xparams_explode
usagexavp_params_implode
usagexavp_params_implode_qval
usagexavu_params_explode
usagexavu_params_implode
usagexavp_slist_explode
usagexavp_child_seti
usagexavi_child_seti
usagexavp_child_sets
usagexavi_child_sets
usagexavp_rm
usagexavi_rm
usagexavp_child_rm
usagexavi_child_rm
usagexavp_lshift
usagexavp_push_dst
usagesbranch_set_ruri()
usagesbranch_append()
usagesbranch_append()
usagepv_xavp_print()
usagepv_xavu_print()
usagepv_xavi_print()
usagepv_var_to_xavp()
usagepv_xavp_to_var()
usagepv_xavp_to_var()
usagepv.shvSet
usagepv.shvGet
usageTable of Contents
pv_isset(pvar)
pv_unset(pvar)
is_int(pvar)
typeof(pvar, vtype)
not_empty(pvar)
xavp_copy(source_name, source_index, destination_name)
xavp_copy(source_name, source_index, destination_name, destination_index)
xavp_params_explode(sparams, xname)
xavp_xparams_explode(sparams, sep, xname)
xavp_params_implode(xname, pvname)
xavp_params_implode_qval(xname, pvname)
xavu_params_explode(sparams, xname)
xavu_params_implode(xname, pvname)
xavp_slist_explode(slist, sep, mode, xname)
xavp_child_seti(rname, cname, ival)
xavi_child_seti(rname, cname, ival)
xavp_child_sets(rname, cname, sval)
xavi_child_sets(rname, cname, sval)
xavp_rm(rname)
xavi_rm(rname)
xavp_child_rm(rname, cname)
xavi_child_rm(rname, cname)
xavp_lshift(xname, idx)
xavp_push_dst(xname)
sbranch_set_ruri()
sbranch_append()
sbranch_reset()
pv_xavp_print()
pv_xavu_print()
pv_xavi_print()
pv_var_to_xavp(varname, xname)
pv_xavp_to_var(xname)
pv_evalx(dst, fmt)
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
The following modules must be loaded before this module:
No dependencies on other Kamailio modules.
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") ...
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") ...
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.
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.
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"); } ...
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"); } ...
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"); } ...
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"); ...
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"); ...
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"; ...
Convert a parameters string in xavp attributes.
The first parameter has to be a string in similar format of SIP header parameters (name1=value1;...;nameN=valueN), but the separator can be other character than ';'. The second parameter is the separator for the parameters list. The third 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.12. xavp_xparams_explode
usage
... xavp_xparams_explode("a=b,c=d,e=d", ",", "x"); # results in: # $xavp(x=>a) = "b"; # $xavp(x=>c) = "d"; # $xavp(x=>e) = "f"; ...
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.13. 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;" ...
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.14. 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"; ...
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.15. 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"; ...
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.16. 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;" ...
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.17. 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"; ...
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.18. xavp_child_seti
usage
... $var(n) = 10; xavp_child_seti("x", "y", "$var(n)"); # results in: $xavp(x=>y) is 10 ...
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.19. xavi_child_seti
usage
... $var(n) = 10; xavi_child_seti("WhatEver", "FoO", "$var(n)"); # results in: $xavi(whatever=>foo) is 10 ...
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.20. xavp_child_sets
usage
... $var(n) = 10; xavp_child_sets("x", "y", "Count: $var(n)"); # results in: $xavp(x=>y) is "Count: 10" ...
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.21. xavi_child_sets
usage
... $var(n) = 10; xavi_child_sets("WhatEver", "FoO", "Count: $var(n)"); # results in: $xavi(whatever=>foo) is "Count: 10" ...
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.
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.
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.24. xavp_child_rm
usage
... xavp_child_rm("x", "y"); # same result as: $xavp(x=>y) = $null; ...
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.25. xavi_child_rm
usage
... xavi_child_rm("WhatEver", "FoO"); # same result as: $xavi(whatever=>foo) = $null; ...
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.26. 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 ...
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.27. 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"); ...
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.28. 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(); ...
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.29. 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(); ...
Reset the content of static branch ($sbranch(key) variable.
Function can be used from REQUEST_ROUTE, BRANCH_ROUTE or FAILURE_ROUTE.
Print all XAVPs to the syslog using INFO log level.
Function can be used from ANY_ROUTE.
Print all XAVUs to the syslog using INFO log level.
Function can be used from ANY_ROUTE.
Print all XAVIs to the syslog using INFO log level.
Function can be used from ANY_ROUTE.
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.34. 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" ...
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.35. 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" ...
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.36. 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" ...
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