<?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 extensions from &kamailio; core.
	</para>
	<para>
	&kamailio; Core CookBook is available at:
	<ulink url="http://kamailio.org/dokuwiki/">
	http://kamailio.org/dokuwiki/</ulink>
	</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>Functions</title>
		<section id="kex.f.setsflag">
		<title><function moreinfo="none">setsflag(flag)</function></title>
		<para>
			Set the script flag.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
				<emphasis>flag</emphasis> - the index of the script flag to
				be set. Can be integer or pseudo-variable with integer value.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>setsflag</function> usage</title>
		<programlisting format="linespecific">
...
setsflag("1");
...
$var(flag) = 11;
setsflag("$var(flag)");
...
</programlisting>
		</example>
		</section>
		<section id="kex.f.issflagset">
		<title><function moreinfo="none">issflagset(flag)</function></title>
		<para>
			Return true of the script flag is set.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
				<emphasis>flag</emphasis> - the index of the script flag to
				be tested. Can be integer or pseudo-variable with integer value.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>issflagset</function> usage</title>
		<programlisting format="linespecific">
...
if(issflagset("1"))
{
    ...
}
...
</programlisting>
		</example>
		</section>
		<section id="kex.f.resetsflag">
		<title><function moreinfo="none">resetsflag(flag)</function></title>
		<para>
			Reset the script flag.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
				<emphasis>flag</emphasis> - the index of the script flag to
				be reset. Can be integer or pseudo-variable with integer value.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>resetsflag</function> usage</title>
		<programlisting format="linespecific">
...
resetsflag("1");
...
</programlisting>
		</example>
		</section>
		<section id="kex.f.setbflag">
		<title><function moreinfo="none">setbflag(flag [, branch])</function></title>
		<para>
			Set the branch flag.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
				<emphasis>flag</emphasis> - the index of the branch flag to
				be set. Can be integer or pseudo-variable with integer value.
			</para>
		</listitem>
		<listitem>
			<para>
				<emphasis>branch</emphasis> - the index of the branch whose
				flag to be set. Can be integer or pseudo-variable with integer
				value. If omitted, then branch 0 is used (R-URI).
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>setbflag</function> usage</title>
		<programlisting format="linespecific">
...
setbflag("1");
...
$var(flag) = 11;
setbflag("$var(flag)", "1");
...
</programlisting>
		</example>
		</section>
		<section id="kex.f.isbflagset">
		<title><function moreinfo="none">isbflagset(flag [, branch])</function></title>
		<para>
			Return true of the branch flag is set.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
				<emphasis>flag</emphasis> - the index of the branch flag to
				be tested. Can be integer or pseudo-variable with integer value.
			</para>
		</listitem>
		<listitem>
			<para>
				<emphasis>branch</emphasis> - the index of the branch whose
				flag to be set. Can be integer or pseudo-variable with integer
				value. If omitted, then branch 0 is used (R-URI).
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>isbflagset</function> usage</title>
		<programlisting format="linespecific">
...
if(isbflagset("1"))
{
    ...
}
...
</programlisting>
		</example>
		</section>
		<section id="kex.f.resetbflag">
		<title><function moreinfo="none">resetbflag(flag [, branch])</function></title>
		<para>
			Reset the branch flag.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
				<emphasis>flag</emphasis> - the index of the branch flag to
				be reset. Can be integer or pseudo-variable with integer value.
			</para>
		</listitem>
		<listitem>
			<para>
				<emphasis>branch</emphasis> - the index of the branch whose
				flag to be set. Can be integer or pseudo-variable with integer
				value. If omitted, then branch 0 is used (R-URI).
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>resetbflag</function> usage</title>
		<programlisting format="linespecific">
...
resetbflag("1");
...
</programlisting>
		</example>
		</section>
		<section id="kex.f.setdsturi">
		<title><function moreinfo="none">setdsturi(uri)</function></title>
		<para>
			Set the destination address URI (outbound proxy address).
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
				<emphasis>uri</emphasis> - Valid SIP URI representing the
				address where to send the request. It must be a static string,
				no variables are evaluated at runtime. If you need to set
				outbound proxy address via a variable, use assginment to
				<emphasis>$du</emphasis>.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>setdsturi</function> usage</title>
		<programlisting format="linespecific">
...
setdsturi("sip:10.0.0.10");
...
</programlisting>
		</example>
		</section>
		<section id="kex.f.resetdsturi">
		<title><function moreinfo="none">resetdsturi()</function></title>
		<para>
			Reset the destination address URI (outbound proxy address).
		</para>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>resetdsturi</function> usage</title>
		<programlisting format="linespecific">
...
resetdsturi();
...
</programlisting>
		</example>
		</section>
		<section id="kex.f.isdsturiset">
		<title><function moreinfo="none">isdsturiset()</function></title>
		<para>
			Check if the destination address URI (outbound proxy address)
			is set.
		</para>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>isdsturiset</function> usage</title>
		<programlisting format="linespecific">
...
if(isdsturiset())
{
   ...
}
...
</programlisting>
		</example>
		</section>
		<section id="kex.f.pv_printf">
		<title><function moreinfo="none">pv_printf(var, str)</function></title>
		<para>
			Evalues the str and sets the resulting value to variable var. For
			backward compatibility reasons, the same function can be executed via
			'avp_printf(var, str)'.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
				<emphasis>var</emphasis> - name of a writable variable
			</para>
		</listitem>
		<listitem>
			<para>
				<emphasis>str</emphasis> - string that may contain variables
				which will be evaluated at runtime.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>pv_printf</function> usage</title>
		<programlisting format="linespecific">
...
pv_printf("$ru", "sip:$rU@$fd");
pv_printf("$avp(x)", "From: $fU - To: $tU");
...
</programlisting>
		</example>
		</section>
		<section id="kex.f.is_myself">
		<title><function moreinfo="none">is_myself(uri)</function></title>
		<para>
			Check if the parameter matches the 'myself' condition (i.e., is
			a local IP or domain).
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
				<emphasis>uri</emphasis> - Valid SIP URI or IP address to
				check against the list of local IP addresses or domains.
				The parameter value can contain pseudo-variables.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>is_myself</function> usage</title>
		<programlisting format="linespecific">
...
if(is_myself("$fu")) {
    ...
}
...
</programlisting>
		</example>
		</section>
		<section id="kex.f.setdebug">
		<title><function moreinfo="none">setdebug(level)</function></title>
		<para>
			Set the debug log level per process.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
				<emphasis>level</emphasis> - the debug log level to
				be set. Can be integer or pseudo-variable with integer value.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>setdebug</function> usage</title>
		<programlisting format="linespecific">
...
setdebug("1");
...
$var(level) = 2;
setdebug("$var(level)");
...
</programlisting>
		</example>
		</section>
		<section id="kex.f.resetdebug">
		<title><function moreinfo="none">resetdebug()</function></title>
		<para>
		Reset the local debug log level back to the value of core parameter
		'debug'.
		</para>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>resetdebug</function> usage</title>
		<programlisting format="linespecific">
...
resetdebug();
...
</programlisting>
		</example>
		</section>
		<section id="kex.f.km_append_branch">
		<title><function moreinfo="none">km_append_branch([uri])</function></title>
		<para>
			This function was replaced by append_branch() from corex module, starting with
			version 4.0.0.
		</para>
		</section>
	</section>

	<section>
	<title>MI Commands</title>
	<section id="kex.m.arg">
		<title>
		<function moreinfo="none">arg</function>
		</title>
		<para>
		Print command line arguments.
		</para>
		<para>
		Name: <emphasis>arg</emphasis>
		</para>
		<para>Parameters: <emphasis>none</emphasis>.</para>
 		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:arg:_reply_fifo_file_
		_empty_line_
		</programlisting>
    	</section>
	<section id="kex.m.kill">
		<title>
		<function moreinfo="none">kill</function>
		</title>
		<para>
		Kill the application.
		</para>
		<para>
		Name: <emphasis>kill</emphasis>
		</para>
		<para>Parameters: <emphasis>none</emphasis>.</para>
 		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:kill:_reply_fifo_file_
		_empty_line_
		</programlisting>
    	</section>
	<section id="kex.m.pwd">
		<title>
		<function moreinfo="none">pwd</function>
		</title>
		<para>
		Print working directory.
		</para>
		<para>
		Name: <emphasis>pwd</emphasis>
		</para>
		<para>Parameters: <emphasis>none</emphasis>.</para>
 		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:pwd:_reply_fifo_file_
		_empty_line_
		</programlisting>
    	</section>
	<section id="kex.m.uptime">
		<title>
		<function moreinfo="none">uptime</function>
		</title>
		<para>
		Print uptime.
		</para>
		<para>
		Name: <emphasis>uptime</emphasis>
		</para>
		<para>Parameters: <emphasis>none</emphasis>.</para>
 		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:uptime:_reply_fifo_file_
		_empty_line_
		</programlisting>
    </section>
	<section id="kex.m.version">
		<title>
		<function moreinfo="none">version</function>
		</title>
		<para>
		Print version information.
		</para>
		<para>
		Name: <emphasis>version</emphasis>
		</para>
		<para>Parameters: <emphasis>none</emphasis>.</para>
 		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:version:_reply_fifo_file_
		_empty_line_
		</programlisting>
    </section>
	<section id="kex.m.which">
		<title>
		<function moreinfo="none">which</function>
		</title>
		<para>
		Print list of available MI commands.
		</para>
		<para>
		Name: <emphasis>which</emphasis>
		</para>
		<para>Parameters: <emphasis>none</emphasis>.</para>
 		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:which:_reply_fifo_file_
		_empty_line_
		</programlisting>
    </section>
	<section id="kex.m.get_statistics">
		<title>
		<function moreinfo="none">get_statistics</function>
		</title>
		<para>
		Print the list of available internal statistics.
		</para>
		<para>
		Name: <emphasis>get_statistics</emphasis>
		</para>
		<para>Parameters: <emphasis>statsid</emphasis> - which statistics to
			be printed. If set to 'all' then all statistics are printed; if
			set to 'statsgroup:' then all statistics in the group are printed;
			if set to 'statsname' then the statistics identified by the name
			is printed.</para>
 		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:get_statistics:_reply_fifo_file_
		_statsid_
		_empty_line_
		</programlisting>
    </section>
	<section id="kex.m.reset_statistics">
		<title>
		<function moreinfo="none">reset_statistics</function>
		</title>
		<para>
		Reset internal statistics.
		</para>
		<para>
		Name: <emphasis>reset_statistics</emphasis>
		</para>
		<para>Parameters: <emphasis>statsid</emphasis> - which statistics to
			be reset, give as name.</para>
 		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:reset_statistics:_reply_fifo_file_
		_statsid_
		_empty_line_
		</programlisting>
    </section>
	<section id="kex.m.clear_statistics">
		<title>
		<function moreinfo="none">clear_statistics</function>
		</title>
		<para>
			Return statistics and reset their value in one command.
		</para>
		<para>
		Name: <emphasis>get_statistics</emphasis>
		</para>
		<para>Parameters: <emphasis>statsid</emphasis> - same as for
			get_statistics.</para>
 		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:clear_statistics:_reply_fifo_file_
		_statsid_
		_empty_line_
		</programlisting>
    </section>

	</section>

	<section>
	<title>RPC Commands</title>
	<section id="kex.r.pkg.stats">
		<title>
		<function moreinfo="none">pkg.stats</function>
		</title>
		<para>
			Print private memory (pkg) usage statistics per process. It
			can take optinally a filter to print statistics only for a
			specific process or set of processes. If no filter is given,
			it prints statistics for all processes.
		</para>
		<para>The filter can be:</para>
		<itemizedlist>
		<listitem>
			<para>
				<emphasis>pid value</emphasis> - print statistics for
				specific process pid.
			</para>
		</listitem>
		<listitem>
			<para>
				<emphasis>rank value</emphasis> - print statistics for
				specific process rank.
			</para>
		</listitem>
		<listitem>
			<para>
				<emphasis>index value</emphasis> - print statistics for
				specific index in process table.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		Examples:
		</para>
        <programlisting  format="linespecific">
		&sercmd; pkg.stats
		&sercmd; pkg.stats pid 1234
		&sercmd; pkg.stats rank 1
		&sercmd; pkg.stats index 10
		</programlisting>
    </section>
	<section id="kex.r.stats.get_statistics">
		<title>
		<function moreinfo="none">stats.get_statistics</function>
		</title>
		<para>Print the list of available internal statistics.</para>
		<para>Parameters: <emphasis>statsid</emphasis> - which statistics to
			be printed. If set to 'all' then all statistics are printed; if
			set to 'statsgroup:' then all statistics in the group are printed;
			if set to 'statsname' then the statistics identified by the name
			is printed.</para>
		<para>Examples:</para>
        <programlisting  format="linespecific">
		&sercmd; stats.get_statistics all
		&sercmd; stats.get_statistics core:
		&sercmd; stats.get_statistics unsupported_methods
		&sercmd; stats.get_statistics shmem: fwd_requests fwd_replies
		</programlisting>
    </section>
	<section id="kex.r.stats.reset_statistics">
		<title>
		<function moreinfo="none">stats.reset_statistics</function>
		</title>
		<para>Reset internal statistics.</para>
		<para>
		Parameters: <emphasis>statsid</emphasis> - same as for get_statistics.
		</para>
		<para>Examples:</para>
        <programlisting  format="linespecific">
		&sercmd; stats.reset_statistics all
		&sercmd; stats.reset_statistics core:
		&sercmd; stats.reset_statistics unsupported_methods
		&sercmd; stats.reset_statistics shmem: fwd_requests fwd_replies
		</programlisting>
    </section>
	<section id="kex.r.stats.clear_statistics">
		<title>
		<function moreinfo="none">stats.clear_statistics</function>
		</title>
		<para>Return statistics and reset their value in one command.</para>
		<para>
		Parameters: <emphasis>statsid</emphasis> - same as for get_statistics.
		</para>
		<para>Examples:</para>
        <programlisting  format="linespecific">
		&sercmd; stats.reset_statistics all
		&sercmd; stats.reset_statistics core:
		&sercmd; stats.reset_statistics unsupported_methods
		&sercmd; stats.reset_statistics shmem: fwd_requests fwd_replies
		</programlisting>
    </section>
    </section>
</chapter>