tsilo_admin.xml

<?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 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
		adds branches to them later if new contacts for the AOR are added.
	</para>
	<para>
		For each message, the module 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 id="tsilo.p.hash_size">
		<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 id="tsilo.p.use_domain">
		<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 id="tsilo.f.ts_store">
		<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();
        # ts_store("sip:alice@$td");
    }
}
...
</programlisting>
		</example>
	</section>
	<section id="tsilo.f.ts_append">
		<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>Return codes:</para>
		<itemizedlist>
		<listitem>
			<para>
			<emphasis>1</emphasis> - branches added.
			</para>
			<para>
			<emphasis>-1</emphasis> - an internal error has produced (parsing error, memory error).
			</para>
			<para>
      <emphasis>-2</emphasis> - no records found for the r-uri.
			</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 id="tsilo.f.ts_append_by_contact">
		<title><function moreinfo="none">ts_append_by_contact(domain, ruri [, contact])</function></title>
		<para>
		Has almost the same intention as the ts_append(),
		but gives a possibility to append branches
		only for a specific location record (Contact URI).
		The contact's URI value can be either taken from the currently processed REGISTER
		or (optionally) given as a third parameter.
		If the Contact URI for a lookup is given as the parameter,
		it is possible to provide it as a pseudo-variable.

		The contact lookup is performed 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>
		<listitem>
			<para>
			<emphasis>contact</emphasis> - Optional, a value of the location record
			(contact URI) based on which to perform the branch appending.
			If not given, the value will be taken from the currently processed REGISTER.
			If a location lookup based on this Contact URI fails (no location record found),
			then the branch append will not happen.
			</para>
		</listitem>
		</itemizedlist>
		<para>Return codes:</para>
		<itemizedlist>
		<listitem>
			<para>
			<emphasis>1</emphasis> - branches added.
			</para>
			<para>
			<emphasis>-1</emphasis> - an internal error has produced (parsing error, memory error).
			</para>
			<para>
      <emphasis>-2</emphasis> - no records found for the r-uri.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>ts_append_by_contact</function> usage</title>
		<programlisting format="linespecific">
...
if (is_method("REGISTER")) {
	$var(formatted_ct) = $(x_hdr(Contact){nameaddr.uri});
	ts_append_by_contact("location", "$tu", "$var(formatted_ct)");
}
...
</programlisting>
		</example>
	</section>
	<section id="tsilo.f.ts_append_to">
		<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> (optional) - 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>RPC Commands</title>
		<section id="tsilo.rpc.ts.dump">
			<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 id="tsilo.rpc.ts.lookup">
			<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 id="tsilo.stat.stored_ruris">
			<title><varname>stored_ruris</varname></title>
			<para>
			Number of ruris currently stored in the TSILO table.
			</para>
		</section>
		<section id="tsilo.stat.stored_transactions">
			<title><varname>stored_transactions</varname></title>
			<para>
			Number of transactions currently stored in the TSILO table.
			</para>
		</section>
		<section id="tsilo.stat.added_branches">
			<title><varname>added_branches</varname></title>
			<para>
			Total number of added branches from the startup.
			</para>
		</section>
		<section id="tsilo.stat.total_ruris">
			<title><varname>total_ruris</varname></title>
			<para>
			Total number of stored ruris from the startup.
			</para>
		</section>
		<section id="tsilo.stat.total_transactions">
			<title><varname>total_transactions</varname></title>
			<para>
			Total number of stored transactions from the startup.
			</para>
		</section>
	</section>
</chapter>