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

