<?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 "../../../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 Dokuwiki:
		<ulink url="http://www.kamailio.org/wiki/">http://www.kamailio.org/wiki/</ulink>,
		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>
		<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>
		<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>
			<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>
		<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>
		<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>
			<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>
			<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>
			<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.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 explicitely 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 explicitely 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 script variables values to a 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>
			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 to vars. Reverse of pv_var_to_xavp().
			</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>

	<section>
		<title><acronym>MI</acronym> Commands</title>
		<section>
			<title><function moreinfo="none">shv_set</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>
		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:shv_set:_reply_fifo_file_
		_name_
		_type_
		_value_
		_empty_line_
		</programlisting>
			<example>
			<title><function moreinfo="none">shv_set</function> usage</title>
			<programlisting format="linespecific">
...
$ &ctltool; fifo shv_set debug int 0
...
</programlisting>
			</example>
		</section>
		<section>
			<title><function moreinfo="none">shv_get</function></title>
			<para>
				Get the value of a shared variable ($shv(name)).
			</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>_name_: shared variable name. If this parameter
			is missing, all shared variables are returned.</para></listitem>
		</itemizedlist>
		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:shv_get:_reply_fifo_file_
		_name_
		_empty_line_
		</programlisting>
			<example>
			<title><function moreinfo="none">shv_get</function> usage</title>
			<programlisting format="linespecific">
...
$ &ctltool; fifo shv_get debug
$ &ctltool; fifo shv_get
...
</programlisting>
			</example>
		</section>
	</section>
	<section>
        <title>RPC Commands</title>
		<section>
			<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>
		</section>
		<section>
			<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>
		</section>
	</section>
	
</chapter>

