<?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 xmlns:xi="http://www.w3.org/2001/XInclude">

	<title>&adminguide;</title>

	<section>
	<title>Overview</title>
	<para>
		This module provides transaction storage for the &kamailioname;. It
		stores in an internal table transactions for a Request-URI (R-URI) and add branches
		to them later if new contacts for the AOR are added.
	</para>
	<para>
		For each message, the modules stores <quote>Request-URI</quote>
		(<quote>R-URI</quote>), &uri; and the internal transaction index
		and label.
	</para>
	<para>
		When a transaction is destroyed by the <emphasis>TM</emphasis> module,
		it is removed from the module's table too.
	</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>REGISTRAR</emphasis>--registrar module-- used to lookup
				for new contacts and update the dset for the r-uri.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>TM</emphasis>--transaction module-- used to
				send &sip; requests.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>SL</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:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>none</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	<section>
	<title>Parameters</title>
	<section>
		<title><varname>hash_size</varname> (integer)</title>
		<para>
		The size of the hash table internally used to keep the transaction. A
		larger table is much faster but consumes more memory. The hash size
		must be a power of two, otherwise it will be rounded down to the nearest
		power of two.
		</para>
		<para>
		<emphasis>
			Default value is <quote>2048</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>hash_size</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tsilo", "hash_size", 1024)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>use_domain</varname> (integer)</title>
		<para>
			Specify if the domain part of the URI should be also saved and used for
			storing and retrieving users' transactions. Useful in multi domain scenarios. 
			Non 0 value means true.
		</para>
		<para>
		<emphasis>
			Default value is <quote>0</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>use_domain</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tsilo", "use_domain", 1)
...
</programlisting>
		</example>
	</section>
	</section>

	<section>
	<title>Functions</title>
	<section>
		<title><function moreinfo="none">ts_store([uri])</function></title>
		<para>
		The method stores uri, tindex and tlabel of the current transaction. If
		the uri parameter is missing, then the value is taken from r-uri. The
		uri parameter can contain variables.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>ts_store</function> usage</title>
		<programlisting format="linespecific">
...
if (is_method("INVITE")) {
    if (t_newtran()) {
        ts_store();
        # t_store("sip:alice@$td");
    }
}
...
</programlisting>
		</example>
	</section>
	<section>
		<title><function moreinfo="none">ts_append(domain, ruri)</function></title>
		<para>
		The method add branches to all the stored transactions for the &sip;
		ruri passed as parameter, performing a contact lookup on the table specified by
		the domain parameter. The method should be called when a REGISTER
		request is received.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
			<emphasis>domain</emphasis> - Name of table that should be used for looking
			up new contacts for r-uri.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>ruri</emphasis> - The r-uri for which we want to check existing
			transactions and add them new branches. Can be a static string value or a
			dynamic string with pseudo-variables.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>ts_append</function> usage</title>
		<programlisting format="linespecific">
...
if (is_method("REGISTER")) {
	ts_append("location", "$tU");
}
...
</programlisting>
		</example>
	</section>
	<section>
		<title><function moreinfo="none">ts_append_to(tindex, tlabel, domain, [uri])</function></title>
		<para>
		The method add branches to the transaction identified by tindex and tlabel,
		performing a contacts lookup on the table specified by the domain parameter.
		The method should be called when a REGISTER request is received.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
                        <emphasis>tindex</emphasis> - internal index of transaction.
                        Can be an integer or a pseudo-variable.
                        </para>
		</listitem>
        <listitem>
			<para>
                        <emphasis>tlabel</emphasis> - internal label of transaction.
                        Can be an integer or a pseudo-variable.
                        </para>
		</listitem>
		<listitem>
			<para>
			<emphasis>domain</emphasis> - Name of table that should be used for looking
			up new contacts for r-uri.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>uri</emphasis> (optiona) - uri for which to do lookup for new
				destinations.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>ts_append_to</function> usage</title>
		<programlisting format="linespecific">
...
if (is_method("REGISTER")) {
	$var(tindex) = ...
	$var(tlabel) = ...
	ts_append_to("$var(tindex)", "$var(tlabel", "location");
}
...
</programlisting>
		</example>
	</section>
	</section>

	<section>
	<title>Exported RPC Functions</title>
		<section>
			<title><varname>ts.dump</varname></title>
			<para>Dumps the content of the TSILO table</para>
			<para>Name: <emphasis>ts.dump</emphasis></para>
			<para>RPC Command Format:</para>
			<programlisting  format="linespecific">
			kamcmd ts.dump
			</programlisting>
		</section>
		<section>
			<title><varname>ts.lookup</varname></title>
			<para>Dumps the transactions stored for the given RURI</para>
			<para>Name: <emphasis>ts.lookup</emphasis></para>
			<para>RPC Command Format:</para>
			<programlisting  format="linespecific">
			kamcmd ts.lookup sip:abcd@example.com
			</programlisting>
		</section>
	</section>
	<section>
		<title>Statistics</title>
		<section>
			<title><varname>stored_ruris</varname></title>
			<para>
			Number of ruris currently stored in the TSILO table.
			</para>
		</section>
		<section>
			<title><varname>stored_transactions</varname></title>
			<para>
			Number of transactions currently stored in the TSILO table.
			</para>
		</section>
		<section>
			<title><varname>added_branches</varname></title>
			<para>
			Total number of added branches from the startup.
			</para>
		</section>
		<section>
			<title><varname>total_ruris</varname></title>
			<para>
			Total number of stored ruris from the startup.
			</para>
		</section>
		<section>
			<title><varname>total_transactions</varname></title>
			<para>
			Total number of stored transactions from the startup.
			</para>
		</section>
	</section>
</chapter>
