<?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_params_explode">
			<title>
				<function moreinfo="none">xavp_params_explode(sparams, xname)</function>
			</title>
			<para>
				Convert a parameters string in xavp atributes.
			</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>
				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_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.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.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.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.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_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>

