<?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; TM module.
	</para>
	<para>
	&kamailio; TM (Transaction Management) module documentation is available at:
	<ulink url="http://www.kamailio.org/docs/modules/1.5.x/tm.html">
	http://www.kamailio.org/docs/modules/1.5.x/tm.html</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>tm</emphasis> -  transaction management.
			</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>
		<title>
		<function moreinfo="none">t_cancel_branches(which)</function>
		</title>
		<para>
		Cancel branches of an active SIP transaction. The function can be
		called for a SIP reply that will identify the current branch.
		</para>
		<para>
		Parameter can be:.
		</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>all</emphasis> - cancel all branches.
			</para></listitem>
			<listitem><para>
				<emphasis>others</emphasis> - cancel all branches but
				the current one.
			</para></listitem>
			<listitem><para>
				<emphasis>this</emphasis> - cancel current branch.
			</para></listitem>
		</itemizedlist>
		<para>
		This function can be used in ONREPLY_ROUTE.
		</para>
		<example>
		<title><function>t_cancel_branches</function> usage</title>
		<programlisting format="linespecific">
...
if (t_cancel_branches("all")) {
	xlog("cancelled all branches\n");
}
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
			<function moreinfo="none">t_cancel_callid(callid, cseq, flag)
			</function>
		</title>
		<para>
		Cancel first INVITE transaction identified by callid and cseq. It sets
		the flag if the value is greater than zero
		</para>
		<para>
		Parameters:.
		</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>callid</emphasis> - call-id value.
			</para></listitem>
			<listitem><para>
				<emphasis>cseq</emphasis> - cseq number.
			</para></listitem>
			<listitem><para>
				<emphasis>flag</emphasis> - index of the flag to set.
			</para></listitem>
		</itemizedlist>
		<para>
		This function can be used in ANY_ROUTE.
		</para>
		<example>
		<title><function>t_cancel_callid</function> usage</title>
		<programlisting format="linespecific">
...
if (t_cancel_callid("123qaz", "5", "22")) {
	xlog("transaction cancelled\n");
}
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
			<function moreinfo="none">t_reply_callid(callid, cseq, code, reason)
			</function>
		</title>
		<para>
		Send reply to first INVITE transaction identified by callid and cseq.
		</para>
		<para>
		Parameters:.
		</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>callid</emphasis> - call-id value.
			</para></listitem>
			<listitem><para>
				<emphasis>cseq</emphasis> - cseq number.
			</para></listitem>
			<listitem><para>
				<emphasis>code</emphasis> - reply code.
			</para></listitem>
			<listitem><para>
				<emphasis>reason</emphasis> - reply reason.
			</para></listitem>
		</itemizedlist>
		<para>
		This function can be used in ANY_ROUTE.
		</para>
		<example>
		<title><function>t_reply_callid</function> usage</title>
		<programlisting format="linespecific">
...
if (t_reply_callid("123qaz", "5", "458", "Replied remotely")) {
	xlog("transaction replied\n");
}
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
		<function moreinfo="none">t_flush_flags()</function>
		</title>
		<para>
		Flush the flags from current SIP message into the already created 
		transaction. It make sense only in routing block if the transaction was
		created via t_newtran() and the flags have been altered since.
		</para>
		<para>
		This function can be used from ANY_ROUTE .
		</para>
		<example>
		<title><function>t_flush_flags</function> usage</title>
		<programlisting format="linespecific">
...
t_flush_flags();
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
		<function moreinfo="none">t_is_failure_route()</function>
		</title>
		<para>
		Returns true if the top-executed route block is failure_route.
		</para>
		<para>
		This function can be used from ANY_ROUTE .
		</para>
		<example>
		<title><function>t_is_failure_route</function> usage</title>
		<programlisting format="linespecific">
...
failure_route[xyz] {
    route(abc);
}

route[abc] {
    if(t_is_failure_route()) { ... }
}
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
		<function moreinfo="none">t_is_branch_route()</function>
		</title>
		<para>
		Returns true if the top-executed route block is branch_route.
		</para>
		<para>
		This function can be used from ANY_ROUTE .
		</para>
		<example>
		<title><function>t_is_branch_route</function> usage</title>
		<programlisting format="linespecific">
...
branch_route[xyz] {
    route(abc);
}

route[abc] {
    if(t_is_branch_route()) { ... }
}
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
		<function moreinfo="none">t_is_reply_route()</function>
		</title>
		<para>
		Returns true if the top-executed route block is reply_route.
		</para>
		<para>
		This function can be used from ANY_ROUTE .
		</para>
		<example>
		<title><function>t_is_reply_route</function> usage</title>
		<programlisting format="linespecific">
...
reply_route[xyz] {
    route(abc);
}

route[abc] {
    if(t_is_reply_route()) { ... }
}
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
		<function moreinfo="none">t_suspend()</function>
		</title>
		<para>
		Suspend the execution of SIP request in a transaction. If transaction
		was not created yet, it is created by this function. Returns true in
		case of success and internal transaction index and label are available
		via $T(id_index) and $T(id_label).
		</para>
		<para>
		This function can be used from ANY_ROUTE .
		</para>
		<example>
		<title><function>t_suspend</function> usage</title>
		<programlisting format="linespecific">
...
if(t_suspend())
{
    xlog("proceesing suspended in trasaction [$T(id_index):$T(id_label)]\n");
    exit;
}
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
			<function moreinfo="none">t_continue(tindex, tlabel, rtname)
			</function>
		</title>
		<para>
		Continue the execution of the transaction identified by tindex and
		tlabel with the actions defined in route[rtname].
		</para>
		<para>
		Parameters:.
		</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>rtname</emphasis> - the name of the route block to
				execute. Can be a static string value or a dynamic string with
				pseudo-variables.
			</para></listitem>
		</itemizedlist>
		<para>
		This function can be used in ANY_ROUTE.
		</para>
		<example>
		<title><function>t_continue</function> usage</title>
		<programlisting format="linespecific">
...
tcontinue('123', '456', 'MYROUTE');
...
</programlisting>
		</example>
	</section>
	</section>

	<section>
		<title>Exported pseudo-variables</title>
		<itemizedlist>
			<listitem><para>
				<emphasis>$T_branch_idx</emphasis>
			</para></listitem>
			<listitem><para>
				<emphasis>$T_reply_code</emphasis>
			</para></listitem>
			<listitem><para>
				<emphasis>$T_reply_reason</emphasis>
			</para></listitem>
			<listitem><para>
				<emphasis>$T_reply_last</emphasis>
			</para></listitem>
			<listitem><para>
				<emphasis>$T_req(pv)</emphasis>
			</para></listitem>
			<listitem><para>
				<emphasis>$T_rpl(pv)</emphasis>
			</para></listitem>
		</itemizedlist>
		<para>
		Exported pseudo-variables are documented at &kamwikilink;.
		</para>
	</section>


	<section>
	<title>MI Commands</title>

	<section>
		<title>
		<function moreinfo="none">t_uac_dlg</function>
		</title>
		<para>
		Generates and sends a local SIP request.
		</para>
		<para>Parameters: </para>
		<itemizedlist>
			<listitem><para>
				<emphasis>method</emphasis> - request method
			</para></listitem>
			<listitem><para>
				<emphasis>RURI</emphasis> - request SIP URI
			</para></listitem>
			<listitem><para>
				<emphasis>NEXT HOP</emphasis> - next hop SIP URI (OBP);
				use <quote>.</quote> if no value.
			</para></listitem>
			<listitem><para>
				<emphasis>socket</emphasis> - local socket to be used for
				sending the request; use <quote>.</quote> if no value.
			</para></listitem>
			<listitem><para>
				<emphasis>headers</emphasis> - set of additional headers to
				be added to the request; at least 
				<quote>From</quote> and <quote>To</quote> headers must be
				specify)
			</para></listitem>
			<listitem><para>
				<emphasis>body</emphasis> - (optional, may not be present)
				request body (if present, requires the 
				<quote>Content-Type</quote> and <quote>Content-length</quote>
				headers)
			</para></listitem>
		</itemizedlist>
	</section>

	<section>
		<title>
		<function moreinfo="none">t_uac_cancel</function>
		</title>
		<para>
		Generates and sends a CANCEL for an existing local SIP request.
		</para>
		<para>Parameters: </para>
		<itemizedlist>
			<listitem><para>
				<emphasis>callid</emphasis> - callid of the INVITE request
				to be cancelled.
			</para></listitem>
			<listitem><para>
				<emphasis>cseq</emphasis> - cseq of the INVITE request to be
				cancelled.
			</para></listitem>
		</itemizedlist>
	</section>

	<section>
		<title>
		<function moreinfo="none">t_hash</function>
		</title>
		<para>
		Gets information about the load of TM internal hash table.
		</para>
		<para>Parameters: </para>
		<itemizedlist>
			<listitem><para>
				<emphasis>none</emphasis>
			</para></listitem>
		</itemizedlist>
	</section>

	<section>
		<title>
		<function moreinfo="none">t_reply</function>
		</title>
		<para>
		Generates and sends a reply for an existing inbound SIP transaction.
		</para>
		<para>Parameters: </para>
		<itemizedlist>
			<listitem><para>
				<emphasis>code</emphasis> - reply code
			</para></listitem>
			<listitem><para>
				<emphasis>reason</emphasis> - reason phrase.
			</para></listitem>
			<listitem><para>
				<emphasis>trans_id</emphasis> - transaction identifier
				(has the hash_entry:label format)
			</para></listitem>
			<listitem><para>
				<emphasis>to_tag</emphasis> - To tag to be added to TO header
			</para></listitem>
			<listitem><para>
				<emphasis>new_headers</emphasis> - extra headers to be
				appended to the reply; use a dot (<quote>.</quote>) char 
				only if there are no headers;
			</para></listitem>
			<listitem><para>
				<emphasis>body</emphasis> - (optional, may not be present)
				reply body (if present, requires the 
				<quote>Content-Type</quote> and <quote>Content-length</quote>
				headers)
			</para></listitem>
		</itemizedlist>
	</section>
	<section>
		<title>
		<function moreinfo="none">t_reply_callid</function>
		</title>
		<para>
		Generates and sends a reply for an existing inbound SIP transaction.
		</para>
		<para>Parameters: </para>
		<itemizedlist>
			<listitem><para>
				<emphasis>code</emphasis> - reply code
			</para></listitem>
			<listitem><para>
				<emphasis>reason</emphasis> - reason phrase.
			</para></listitem>
			<listitem><para>
				<emphasis>callid</emphasis> - SIP Call-ID header
			</para></listitem>
			<listitem><para>
				<emphasis>cseq</emphasis> - SIP CSeq header
			</para></listitem>
			<listitem><para>
				<emphasis>to_tag</emphasis> - To tag to be added to TO header
			</para></listitem>
			<listitem><para>
				<emphasis>new_headers</emphasis> - extra headers to be
				appended to the reply; use a dot (<quote>.</quote>) char 
				only if there are no headers;
			</para></listitem>
			<listitem><para>
				<emphasis>body</emphasis> - (optional, may not be present)
				reply body (if present, requires the 
				<quote>Content-Type</quote> and <quote>Content-length</quote>
				headers)
			</para></listitem>
		</itemizedlist>
	</section>

	</section>


	<section>
		<title>Statistics</title>
		<para>
		Exported statistics are listed in the next sections. All statistics
		except <quote>inuse_transactions</quote> can be reset.
		</para>
		<section>
		<title>received_replies</title>
			<para>
			Total number of total replies received by TM module.
			</para>
		</section>
		<section>
		<title>relayed_replies</title>
			<para>
			Total number of replies received and relayed by TM module.
			</para>
		</section>
		<section>
		<title>local_replies</title>
			<para>
			Total number of replies local generated by TM module.
			</para>
		</section>
		<section>
		<title>UAS_transactions</title>
			<para>
			Total number of transactions created by received requests.
			</para>
		</section>
		<section>
		<title>UAC_transactions</title>
			<para>
			Total number of transactions created by local generated requests.
			</para>
		</section>
		<section>
		<title>2xx_transactions</title>
			<para>
			Total number of transactions completed with 2xx replies.
			</para>
		</section>
		<section>
		<title>3xx_transactions</title>
			<para>
			Total number of transactions completed with 3xx replies.
			</para>
		</section>
		<section>
		<title>4xx_transactions</title>
			<para>
			Total number of transactions completed with 4xx replies.
			</para>
		</section>
		<section>
		<title>5xx_transactions</title>
			<para>
			Total number of transactions completed with 5xx replies.
			</para>
		</section>
		<section>
		<title>6xx_transactions</title>
			<para>
			Total number of transactions completed with 6xx replies.
			</para>
		</section>
		<section>
		<title>inuse_transactions</title>
			<para>
			Number of transactions existing in memory at current time.
			</para>
		</section>
	</section>
</chapter>

