pv_admin.xml

<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
%docentities;

]>
<!-- Module User's Guide -->

<chapter>

	<title>&adminguide;</title>

	<section>
	<title>Overview</title>
	<para>
		This module collects the core pseudo-variables that can be used in
		configuration file. They are listed in wiki: &kamwikilink;
		in Pseudo-Variables section
	</para>
	</section>
	<section>
	<title>Dependencies</title>
	<section>
		<title>&kamailio; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>No dependencies on other &kamailio; modules</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before running
		&kamailio; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	<section>
	<title>Parameters</title>
	<section id="pv.p.shvset">
		<title><varname>shvset</varname> (string)</title>
		<para>
		Set the initial value of a shared variable ($shv(name)). The parameter
		can be set many times.
		</para>
		<para>
		The value of the parameter has the format:
		_name_ '=' _type_ ':' _value_
		</para>
		<itemizedlist>
			<listitem><para>_name_: shared variable name</para></listitem>

			<listitem><para>_type_: type of the value</para>
			 <itemizedlist>
	    <listitem><para> <quote>i</quote>: integer value </para></listitem>
		<listitem><para> <quote>s</quote>: string value </para></listitem>
		      </itemizedlist>
			</listitem>

			<listitem><para>_value_: value to be set</para></listitem>
		</itemizedlist>
		<para>
		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.
		</para>
		<para>
		Default value is <quote>NULL</quote>.
		</para>
		<example>
		<title><varname>shvset</varname> parameter usage</title>
		<programlisting format="linespecific">
...
modparam("pv", "shvset", "debug=i:1")
modparam("pv", "shvset", "pstngw=s:sip:10.10.10.10")
...
</programlisting>
	    </example>
	</section>
	<section id="pv.p.varset">
		<title><varname>varset</varname> (string)</title>
		<para>
		Set the value of a script variable ($var(name)). The parameter
		can be set many times.
		</para>
		<para>
		The value of the parameter has the format:
		_name_ '=' _type_ ':' _value_
		</para>
		<itemizedlist>
			<listitem><para>_name_: shared variable name</para></listitem>

			<listitem><para>_type_: type of the value</para>
			 <itemizedlist>
	     <listitem><para> <quote>i</quote>: integer value </para></listitem>
		 <listitem><para> <quote>s</quote>: string value </para></listitem>
			 </itemizedlist>
			</listitem>

			<listitem><para>_value_: value to be set</para></listitem>
		</itemizedlist>
		<para>
		Default value is <quote>NULL</quote>.
		</para>
		<example>
		<title><varname>varset</varname> parameter usage</title>
		<programlisting format="linespecific">
...
modparam("pv", "varset", "init=i:1")
modparam("pv", "varset", "gw=s:sip:11.11.11.11;transport=tcp")
...
</programlisting>
	    </example>
	</section>
		<section id="pv.p.avp_aliases">
			<title><varname>avp_aliases</varname> (string)</title>
			<para>
			Define aliases for PV AVP names.
			</para>
			<para>
				<emphasis>
					Default value is NULL.
				</emphasis>
			</para>
			<example>
				<title><varname>avp_aliases</varname> parameter usage</title>
				<programlisting format="linespecific">
...
modparam("pv","avp_aliases","email=s:email_addr;tmp=i:100")
...
				</programlisting>
			</example>
		</section>
	</section>
	<section>
	<title>Functions</title>
		<section id="pv.f.pv_isset">
		<title><function moreinfo="none">pv_isset(pvar)</function></title>
		<para>
			Return true if a PV value is different than 'null'.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
				<emphasis>pvar</emphasis> - pvar identifier.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>pv_isset</function> usage</title>
		<programlisting format="linespecific">
...
if(pv_isset("$avp(s:x)"))
{
    ...
}
...
</programlisting>
		</example>
		</section>
		<section id="pv.f.pv_unset">
		<title><function moreinfo="none">pv_unset(pvar)</function></title>
		<para>
			Unset the value of the PV (e.g., delete AVP, set to null).
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
				<emphasis>pvar</emphasis> - pvar identifier.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>pv_unset</function> usage</title>
		<programlisting format="linespecific">
...
pv_unset("$avp(s:x)");
...
</programlisting>
		</example>
		</section>
		<section id="pv.f.is_int">
			<title>
				<function moreinfo="none">is_int(pvar)</function>
			</title>
			<para>
			Function checks if pvar argument contains integer value
			and returns 1 if it does and -1 otherwise.
			</para>
			<para>
			Function can be used from all kinds of routes.
			</para>
			<example>
				<title><function>is_int()</function> usage</title>
				<programlisting format="linespecific">
...
if (is_int("$var(foo)")) {
    xlog("L_INFO", "variable foo contains integer value\n");
}
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.typeof">
			<title>
				<function moreinfo="none">typeof(pvar, vtype)</function>
			</title>
			<para>
			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.
			</para>
			<para>
			Function can be used from ANYROUTE.
			</para>
			<example>
				<title><function>typeof()</function> usage</title>
				<programlisting format="linespecific">
...
if (typeof("$var(foo)", "str")) {
    xdbg("variable foo is a string\n");
}
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.not_empty">
			<title>
				<function moreinfo="none">not_empty(pvar)</function>
			</title>
			<para>
			Returns true if the pseudo-variables has the type string and
			is not empty value.
			</para>
			<para>
			Function can be used from all kinds of routes.
			</para>
			<example>
				<title><function>not_empty()</function> usage</title>
				<programlisting format="linespecific">
...
if (not_empty("$var(foo)")) {
    append_hf("X-Foo: $var(foo)\r\n");
}
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.xavp_copy">
			<title>
				<function moreinfo="none">xavp_copy(source_name, source_index, destination_name)</function>
			</title>
			<para>
				Copy and append one XAVP.
			</para>
			<para>
				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.
			</para>
			<para>
			Function can be used from ANY ROUTE.
			</para>
			<example>
				<title><function>xavp_copy</function> usage</title>
				<programlisting format="linespecific">
...
# Using xavp_copy to reorder an existing xavp stack in a new one
$xavp(a=&gt;x) = "a-0-x";
$xavp(a[0]=&gt;y) = "a-0-y";
$xavp(a=&gt;x) = "a-1-x";
$xavp(a[0]=&gt;y) = "a-1-y";
$xavp(a=&gt;x) = "a-2-x";
$xavp(a[0]=&gt;y) = "a-2-y";

xinfo("BEFORE $xavp(a[0]=&gt;x) == [a-2-x] == $xavp(a[0]=&gt;y) == [a-2-y]\n");
xinfo("BEFORE $xavp(a[1]=&gt;x) == [a-1-x] == $xavp(a[1]=&gt;y) == [a-1-y]\n");
xinfo("BEFORE $xavp(a[2]=&gt;x) == [a-0-x] == $xavp(a[2]=&gt;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]=&gt;x) == [a-0-x] == $xavp(b[0]=&gt;y) == [a-0-y]\n");
xinfo("AFTER $xavp(b[1]=&gt;x) == [a-1-x] == $xavp(b[1]=&gt;y) == [a-1-y]\n");
xinfo("AFTER $xavp(b[2]=&gt;x) == [a-2-x] == $xavp(b[2]=&gt;y) == [a-2-y]\n");
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.xavp_copy2">
			<title>
				<function moreinfo="none">xavp_copy(source_name, source_index, destination_name, destination_index)</function>
			</title>
			<para>
				Copy and replace one XAVP.
			</para>
			<para>
				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.
			</para>
			<para>
			Function can be used from ANY ROUTE.
			</para>
			<example>
				<title><function>xavp_copy</function> usage</title>
				<programlisting format="linespecific">
...
# Using xavp_copy to reorder an existing xavp stack inplace
$xavp(d=&gt;x) = "d-0-x";
$xavp(d[0]=&gt;y) = "d-0-y";
$xavp(d=&gt;x) = "d-1-x";
$xavp(d[0]=&gt;y) = "d-1-y";
$xavp(d=&gt;x) = "d-2-x";
$xavp(d[0]=&gt;y) = "d-2-y";

xinfo("NEW $xavp(d[0]=&gt;x) == [d-2-x] and $xavp(d[0]=&gt;y) == [d-2-y]\n");
xinfo("NEW $xavp(d[1]=&gt;x) == [d-1-x] and $xavp(d[1]=&gt;y) == [d-1-y]\n");
xinfo("NEW $xavp(d[2]=&gt;x) == [d-0-x] and $xavp(d[2]=&gt;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]=&gt;x) == [d-0-x] $xavp(d[0]=&gt;y) == [d-0-y]\n");
xinfo("AFTER $xavp(d[1]=&gt;x) == [d-1-x] $xavp(d[1]=&gt;y) == [d-1-y]\n");
xinfo("AFTER $xavp(d[2]=&gt;x) == [d-2-x] $xavp(d[2]=&gt;y) == [d-2-y]\n");
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.xavp_params_explode">
			<title>
				<function moreinfo="none">xavp_params_explode(sparams, xname)</function>
			</title>
			<para>
				Convert a parameters string in xavp attributes.
			</para>
			<para>
				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).
			</para>
			<para>
				The values are stored as string type.
			</para>
			<para>
			Function can be used from ANY ROUTE.
			</para>
			<example>
				<title><function>xavp_params_explode</function> usage</title>
				<programlisting format="linespecific">
...
xavp_params_explode("a=b;c=d;e=d", "x");
# results in:
#    $xavp(x=&gt;a) = "b";
#    $xavp(x=&gt;c) = "d";
#    $xavp(x=&gt;e) = "f";
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.xavp_params_implode">
			<title>
				<function moreinfo="none">xavp_params_implode(xname, pvname)</function>
			</title>
			<para>
				Serialize the subfields in an XAVP to a parameters string format.
			</para>
			<para>
				Number values are serialized as unsigned integer string format.
			</para>
			<para>
				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)).
			</para>
			<para>
				The value is stored as string type.
			</para>
			<para>
			Function can be used from ANY ROUTE.
			</para>
			<example>
				<title><function>xavp_params_implode</function> usage</title>
				<programlisting format="linespecific">
...
$xavp(x=&gt;e) = "f";
$xavp(x[0]=&gt;c) = "d";
$xavp(x[0]=&gt;a) = "b";
xavp_params_implode("x", "$var(out)");
# results in: $var(out) is "a=b;c=d;e=f;"
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.xavp_params_implode_qval">
			<title>
				<function moreinfo="none">xavp_params_implode_qval(xname, pvname)</function>
			</title>
			<para>
				Serialize the subfields in an XAVP to a parameters string format,
				enclosing string values in double quotes.
			</para>
			<para>
				Number values are serialized as unsigned integer string format.
			</para>
			<para>
				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)).
			</para>
			<para>
				The value is stored as string type.
			</para>
			<para>
			Function can be used from ANY ROUTE.
			</para>
			<example>
				<title><function>xavp_params_implode_qval</function> usage</title>
				<programlisting format="linespecific">
...
$xavp(x=&gt;e) = "f";
$xavp(x[0]=&gt;c) = 5;
$xavp(x[0]=&gt;a) = "b";
xavp_params_implode("x", "$var(out)");
# results in: $var(out) is: a="b";c=5;e="f";
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.xavu_params_explode">
			<title>
				<function moreinfo="none">xavu_params_explode(sparams, xname)</function>
			</title>
			<para>
				Convert a parameters string in xavu attributes.
			</para>
			<para>
				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).
			</para>
			<para>
				The values are stored as string type.
			</para>
			<para>
			Function can be used from ANY ROUTE.
			</para>
			<example>
				<title><function>xavu_params_explode</function> usage</title>
				<programlisting format="linespecific">
...
xavu_params_explode("a=b;c=d;e=d", "x");
# results in:
#    $xavu(x=&gt;a) = "b";
#    $xavu(x=&gt;c) = "d";
#    $xavu(x=&gt;e) = "f";
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.xavu_params_implode">
			<title>
				<function moreinfo="none">xavu_params_implode(xname, pvname)</function>
			</title>
			<para>
				Serialize the subfields in an XAUP to a parameters string format.
			</para>
			<para>
				Number values are serialized as unsigned integer string format.
			</para>
			<para>
				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)).
			</para>
			<para>
				The value is stored as string type.
			</para>
			<para>
			Function can be used from ANY ROUTE.
			</para>
			<example>
				<title><function>xavu_params_implode</function> usage</title>
				<programlisting format="linespecific">
...
$xavu(x=&gt;e) = "f";
$xavu(x=&gt;c) = "d";
$xavu(x=&gt;a) = "b";
xavu_params_implode("x", "$var(out)");
# results in: $var(out) is "a=b;c=d;e=f;"
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.xavp_slist_explode">
			<title>
				<function moreinfo="none">xavp_slist_explode(slist, sep, mode, xname)</function>
			</title>
			<para>
				Breaks a string list in tokens by separators and stores them
				in XAVPs. Note that is not storing empty values.
			</para>
			<para>
				The first parameter has to be a string (static or with variables).
			</para>
			<para>
				The second parameter has to contain separator characters (they
				can be many).
			</para>
			<para>
				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.
			</para>
			<para>
				The fourth parameter is the name of the root xavp to hold the tokens
				in fields named 'v' and indexed from 0.
			</para>
			<para>
				The values are stored as string type.
			</para>
			<para>
			Function can be used from ANY ROUTE.
			</para>
			<example>
				<title><function>xavp_slist_explode</function> usage</title>
				<programlisting format="linespecific">
...
xavp_slist_explode("a=b; c=d;", "=;", "t", "x");
# results in:
#    $xavp(x[0]=&gt;v[0]) = "a";
#    $xavp(x[0]=&gt;v[1]) = "b";
#    $xavp(x[0]=&gt;v[2]) = "c";
#    $xavp(x[0]=&gt;v[3]) = "d";
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.xavp_child_seti">
			<title>
				<function moreinfo="none">xavp_child_seti(rname, cname, ival)</function>
			</title>
			<para>
				Set the value of $xavp(rname=&gt;cname) to integer value ival.
			</para>
			<para>
				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.
			</para>
			<para>
			Function can be used from ANY ROUTE.
			</para>
			<example>
				<title><function>xavp_child_seti</function> usage</title>
				<programlisting format="linespecific">
...
$var(n) = 10;
xavp_child_seti("x", "y", "$var(n)");
# results in: $xavp(x=&gt;y) is 10
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.xavi_child_seti">
			<title>
				<function moreinfo="none">xavi_child_seti(rname, cname, ival)</function>
			</title>
			<para>
				Set the value of $xavi(rname=&gt;cname) to integer value ival.
			</para>
			<para>
				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.
			</para>
			<para>
			Function can be used from ANY ROUTE.
			</para>
			<example>
				<title><function>xavi_child_seti</function> usage</title>
				<programlisting format="linespecific">
...
$var(n) = 10;
xavi_child_seti("WhatEver", "FoO", "$var(n)");
# results in: $xavi(whatever=&gt;foo) is 10
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.xavp_child_sets">
			<title>
				<function moreinfo="none">xavp_child_sets(rname, cname, sval)</function>
			</title>
			<para>
				Set the value of $xavp(rname=&gt;cname) to string value sval.
			</para>
			<para>
				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.
			</para>
			<para>
			Function can be used from ANY ROUTE.
			</para>
			<example>
				<title><function>xavp_child_sets</function> usage</title>
				<programlisting format="linespecific">
...
$var(n) = 10;
xavp_child_sets("x", "y", "Count: $var(n)");
# results in: $xavp(x=&gt;y) is "Count: 10"
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.xavi_child_sets">
			<title>
				<function moreinfo="none">xavi_child_sets(rname, cname, sval)</function>
			</title>
			<para>
				Set the value of $xavi(rname=&gt;cname) to string value sval.
			</para>
			<para>
				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.
			</para>
			<para>
			Function can be used from ANY ROUTE.
			</para>
			<example>
				<title><function>xavi_child_sets</function> usage</title>
				<programlisting format="linespecific">
...
$var(n) = 10;
xavi_child_sets("WhatEver", "FoO", "Count: $var(n)");
# results in: $xavi(whatever=&gt;foo) is "Count: 10"
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.xavp_rm">
			<title>
				<function moreinfo="none">xavp_rm(rname)</function>
			</title>
			<para>
				Remove the value of $xavp(rname).
			</para>
			<para>
				The parameter has to be the name of XAVP in the root list.
				It can be static or dynamic string (to include variables).
			</para>
			<para>
			Function can be used from ANY ROUTE.
			</para>
			<example>
				<title><function>xavp_rm</function> usage</title>
				<programlisting format="linespecific">
...
xavp_rm("x");
# same result as: $xavp(x) = $null;
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.xavi_rm">
			<title>
				<function moreinfo="none">xavi_rm(rname)</function>
			</title>
			<para>
				Remove the value of $xavi(rname).
			</para>
			<para>
				The parameter has to be the name of XAVI in the root list.
				It can be static or dynamic string (to include variables).
			</para>
			<para>
			Function can be used from ANY ROUTE.
			</para>
			<example>
				<title><function>xavi_rm</function> usage</title>
				<programlisting format="linespecific">
...
xavi_rm("WhatEver");
# same result as: $xavi(whatever) = $null;
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.xavp_child_rm">
			<title>
				<function moreinfo="none">xavp_child_rm(rname, cname)</function>
			</title>
			<para>
				Remove the value of $xavp(rname=&gt;cname).
			</para>
			<para>
				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).
			</para>
			<para>
			Function can be used from ANY ROUTE.
			</para>
			<example>
				<title><function>xavp_child_rm</function> usage</title>
				<programlisting format="linespecific">
...
xavp_child_rm("x", "y");
# same result as: $xavp(x=&gt;y) = $null;
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.xavi_child_rm">
			<title>
				<function moreinfo="none">xavi_child_rm(rname, cname)</function>
			</title>
			<para>
				Remove the value of $xavi(rname=&gt;cname).
			</para>
			<para>
				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).
			</para>
			<para>
			Function can be used from ANY ROUTE.
			</para>
			<example>
				<title><function>xavi_child_rm</function> usage</title>
				<programlisting format="linespecific">
...
xavi_child_rm("WhatEver", "FoO");
# same result as: $xavi(whatever=&gt;foo) = $null;
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.xavp_lshift">
			<title>
				<function moreinfo="none">xavp_lshift(xname, idx)</function>
			</title>
			<para>
				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.
			</para>
			<para>
				The first parameter has to be the name of XAVP in the root list.
			</para>
			<para>
				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).
			</para>
			<para>
				The parameters can be with variables.
			</para>
			<para>
			Function can be used from ANY ROUTE.
			</para>
			<example>
				<title><function>xavp_lshift</function> usage</title>
				<programlisting format="linespecific">
...
$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
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.xavp_push_dst">
			<title>
				<function moreinfo="none">xavp_push_dst(xname)</function>
			</title>
			<para>
				Set destination fields from XAVP attributes.
			</para>
			<para>
				The first parameter has to be the name of XAVP in the root list.
			</para>
			<para>
				The parameters can be with variables.
			</para>
			<para>
				The attributes that can be stored in the XAVP fields:
			</para>
			<itemizedlist>
				<listitem>
					<para>uri: SIP URI address to set R-URI</para>
				</listitem>
				<listitem>
					<para>dsturi: SIP URI address to set DST-URI</para>
				</listitem>
				<listitem>
					<para>socket: listen address to set outgoing socket</para>
				</listitem>
			</itemizedlist>
			<para>
			Function can be used from REQUEST_ROUTE|BRANCH_ROUTE|FAILURE_ROUTE.
			</para>
			<example>
				<title><function>xavp_push_dst</function> usage</title>
				<programlisting format="linespecific">
...
$xavp(dst=&gt;uri) = "sip:alice@server.com";
$xavp(dst[0]=&gt;dsturi) = "sip:proxy.com";
$xavp(dst[0]=&gt;socket) = "udp:1.2.3.4:5060";
xavp_push_dst("dst");
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.sbranch_set_ruri">
			<title>
				<function moreinfo="none">sbranch_set_ruri()</function>
			</title>
			<para>
				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, ...).
			</para>
			<para>
				Content of the static branch is not reset after this function is
				executed. It has to be done explicitly with sbranch_reset().
			</para>
			<para>
			Function can be used from REQUEST_ROUTE, BRANCH_ROUTE or FAILURE_ROUTE.
			</para>
			<example>
				<title><function>sbranch_set_ruri()</function> usage</title>
				<programlisting format="linespecific">
...
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();
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.sbranch_append">
			<title>
				<function moreinfo="none">sbranch_append()</function>
			</title>
			<para>
				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.
			</para>
			<para>
				Content of the static branch is not reset after this function is
				executed. It has to be done explicitly with sbranch_reset().
			</para>
			<para>
			Function can be used from REQUEST_ROUTE, BRANCH_ROUTE or FAILURE_ROUTE.
			</para>
			<example>
				<title><function>sbranch_append()</function> usage</title>
				<programlisting format="linespecific">
...
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();
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.sbranch_reset">
			<title>
				<function moreinfo="none">sbranch_reset()</function>
			</title>
			<para>
				Reset the content of static branch ($sbranch(key) variable.
			</para>
			<para>
			Function can be used from REQUEST_ROUTE, BRANCH_ROUTE or FAILURE_ROUTE.
			</para>
			<example>
				<title><function>sbranch_append()</function> usage</title>
				<programlisting format="linespecific">
...
sbranch_reset();
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.pv_xavp_print">
			<title>
				<function moreinfo="none">pv_xavp_print()</function>
			</title>
			<para>
				Print all XAVPs to the syslog using INFO log level.
			</para>
			<para>
			Function can be used from ANY_ROUTE.
			</para>
			<example>
				<title><function>pv_xavp_print()</function> usage</title>
				<programlisting format="linespecific">
...
pv_xavp_print();
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.pv_xavu_print">
			<title>
				<function moreinfo="none">pv_xavu_print()</function>
			</title>
			<para>
				Print all XAVUs to the syslog using INFO log level.
			</para>
			<para>
			Function can be used from ANY_ROUTE.
			</para>
			<example>
				<title><function>pv_xavu_print()</function> usage</title>
				<programlisting format="linespecific">
...
pv_xavu_print();
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.pv_xavi_print">
			<title>
				<function moreinfo="none">pv_xavi_print()</function>
			</title>
			<para>
				Print all XAVIs to the syslog using INFO log level.
			</para>
			<para>
			Function can be used from ANY_ROUTE.
			</para>
			<example>
				<title><function>pv_xavi_print()</function> usage</title>
				<programlisting format="linespecific">
...
pv_xavi_print();
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.pv_var_to_xavp">
			<title>
				<function moreinfo="none">pv_var_to_xavp(varname, xname)</function>
			</title>
			<para>
				Copy the script variable value into an xavp.
			</para>
			<para>
				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.
			</para>
			<para>
				Both parameters can contain variables that are evaluated at
				runtime.
			</para>
			<para>
			Function can be used from ANY_ROUTE.
			</para>
			<example>
				<title><function>pv_var_to_xavp()</function> usage</title>
				<programlisting format="linespecific">
...
$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"
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.pv_xavp_to_var">
			<title>
				<function moreinfo="none">pv_xavp_to_var(xname)</function>
			</title>
			<para>
				Copy xavp values into vars. Reverse of pv_var_to_xavp().
			</para>
			<para>
				Both parameters can contain variables that are evaluated at
				runtime.
			</para>
			<para>
			Function can be used from ANY_ROUTE.
			</para>
			<example>
				<title><function>pv_xavp_to_var()</function> usage</title>
				<programlisting format="linespecific">
...
$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"
...
				</programlisting>
			</example>
		</section>
		<section id="pv.f.pv_evalx">
			<title>
				<function moreinfo="none">pv_evalx(dst, fmt)</function>
			</title>
			<para>
				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.
			</para>

			<para>
			Function can be used from ANY_ROUTE.
			</para>
			<example>
				<title><function>pv_xavp_to_var()</function> usage</title>
				<programlisting format="linespecific">
...
$var(x) = "test";
$var(y) = "$var(x)"
pv_evalx("$var(z)", "$var(y) one");

# - the value of $var(z) is "test one"
...
				</programlisting>
			</example>
		</section>
	</section>

	<section>
        <title>RPC Commands</title>
		<section id="pv.rpc.shvSet">
			<title><function moreinfo="none">pv.shvSet</function></title>
			<para>
				Set the value of a shared variable ($shv(name)).
			</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>_name_: shared variable name</para></listitem>

			<listitem><para>_type_: type of the value</para>
			      <itemizedlist>
	    <listitem><para> <quote>int</quote>: integer value </para></listitem>
		<listitem><para> <quote>str</quote>: string value </para></listitem>
				  </itemizedlist>
			</listitem>

			<listitem><para>_value_: value to be set</para></listitem>
		</itemizedlist>
			<example>
			<title><function moreinfo="none">pv.shvSet</function> usage</title>
			<programlisting format="linespecific">
...
$ &kamcmd; pv.shvSet debug int 3
...
</programlisting>
			</example>
		</section>
		<section id="pv.rpc.shvGet">
			<title><function moreinfo="none">pv.shvGet</function></title>
			<para>
				Get the value of a shared variable ($shv(name)).
			</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>_name_: shared variable name</para></listitem>
		</itemizedlist>
		<para>If no name is given, all shared variables are listed.</para>
			<example>
			<title><function moreinfo="none">pv.shvGet</function> usage</title>
			<programlisting format="linespecific">
...
$ &kamcmd; pv.shvGet debug
...
</programlisting>
			</example>

		</section>
	</section>

</chapter>