<?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/stable/tm.html">
	http://www.kamailio.org/docs/modules/stable/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>Parameters</title>
	<section id="tmx.p.precheck_trans">
		<title>
		<function moreinfo="none">precheck_trans</function>
		</title>
		<para>
		Enable/disable transaction pre-check via t_precheck_trans()
		function. If set to 0, the internal structures are not created
		at startup and the funcation will return false always.
		</para>
		<para>
		Default value is <emphasis>1</emphasis> (enabled).
		</para>
		<example>
		<title><function>precheck_trans</function> usage</title>
		<programlisting format="linespecific">
...
modparam("tmx", "precheck_trans", 0)
...
</programlisting>
		</example>
	</section>
	</section>

	<section>
	<title>Functions</title>
	<section id="tmx.f.t_cancel_branches">
		<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 id="tmx.f.t_cancel_callid">
		<title>
			<function moreinfo="none">t_cancel_callid(callid, cseq, flag [, rcode])
			</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>
			<listitem><para>
					<emphasis>rcode</emphasis> - code to be added as
					cause attribute in Reason header for generated
					CANCEL request. This parameter is optional.
			</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");
}
...
if (t_cancel_callid("123qaz", "5", "22", "200")) {
	xlog("transaction cancelled with [Reason: cause=200]\n");
}
...
</programlisting>
		</example>
	</section>
	<section id="tmx.f.t_reply_callid">
		<title>
			<function moreinfo="none">t_reply_callid(callid, cseq, code, reason)
			</function>
		</title>
		<para>
		Send reply to first 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 id="tmx.f.t_flush_flags">
		<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 id="tmx.f.t_is_failure_route">
		<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 id="tmx.f.t_is_branch_route">
		<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 id="tmx.f.t_is_reply_route">
		<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 id="tmx.f.t_is_request_route">
		<title>
		<function moreinfo="none">t_is_request_route()</function>
		</title>
		<para>
		Returns true if the top-executed route block is request_route.
		</para>
		<para>
		This function can be used from ANY_ROUTE .
		</para>
		<example>
		<title><function>t_is_request_route</function> usage</title>
		<programlisting format="linespecific">
...
request_route[xyz] {
    route(abc);
}

route[abc] {
    if(t_is_request_route()) { ... }
}
...
</programlisting>
		</example>
	</section>
	<section id="tmx.f.t_suspend">
		<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 id="tmx.f.t_continue">
		<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>
			Important note: the route[rtname] is executed in the context of
			a failure (same behaviour for functions as they were used in a
			failure_route block).
		</para>
		<para>
		This function can be used in ANY_ROUTE.
		</para>
		<example>
		<title><function>t_continue</function> usage</title>
		<programlisting format="linespecific">
...
t_continue('123', '456', 'MYROUTE');
...
route[MYROUTE] {
  xlog("executed by t continue\n");
  ...
}
...
</programlisting>
		</example>
	</section>

	<section id="tmx.f.t_reuse_branch">
		<title>
		<function moreinfo="none">t_reuse_branch()</function>
		</title>
		<para>
		Creates new "main" branch by making copy of branch-failure
                branch. Currently the following branch attributes are copied
		from branch-failure branch: request-uri, ruid, path, instance,
		and branch flags.
		</para>
		<para>
		This function can be used from tm:branch-failure event_route.
		</para>
		<example>
		<title><function>t_reuse_branch</function> usage</title>
		<programlisting format="linespecific">
...
event_route [tm:branch-failure:contact] {
    t_reuse_branch();
    setbflag(10);
    t_relay();
    exit;
}
...
</programlisting>
		</example>
	</section>
	<section id="tmx.f.t_precheck_trans">
		<title>
		<function moreinfo="none">t_precheck_trans()</function>
		</title>
		<para>
		Check if current processed message is handled by other process.
		This function is useful to catch retransmissions before transaction
		is created. The function returns true if the request is handled by
		another process.
		</para>
		<para>
		Note that ACK and CANCEL requests are not tracked by this function,
		the return code being false for them.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE .
		</para>
		<example>
		<title><function>t_precheck_trans</function> usage</title>
		<programlisting format="linespecific">
...
    # handle retransmissions
    if(t_precheck_trans()) {
        t_check_trans();
        exit;
    }
    t_check_trans();
...
</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>
			<listitem><para>
				<emphasis>$T_reply_ruid</emphasis>
			</para></listitem>
			<listitem><para>
				<emphasis>$T_branch(name)</emphasis>
			</para></listitem>
			<listitem><para>
				<emphasis>$T_inv(pv)</emphasis>
			</para></listitem>
			<listitem><para>
				<emphasis>$T(name)</emphasis>
			</para></listitem>
		</itemizedlist>
		<para>
		Exported pseudo-variables are documented at &kamwikilink;.
		</para>
	</section>


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

	<section id="tmx.mi.t_uac_dlg">
		<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 id="tmx.mi.t_uac_cancel">
		<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 id="tmx.mi.t_hash">
		<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 id="tmx.mi.t_reply">
		<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 id="tmx.mi.t_reply_callid">
		<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>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>
		<title>active_transactions</title>
			<para>
			Number of ongoing transactions at current time.
			</para>
		</section>

		<section>
		<title>rpl_received</title>
			<para>
			Total number of replies received by TM module.
			</para>
		</section>

		<section>
		<title>rpl_absorbed</title>
			<para>
			Total number of replies received and not relayed by TM module.
			</para>
		</section>

		<section>
		<title>rpl_relayed</title>
			<para>
			Total number of replies received and relayed by TM module.
			</para>
		</section>

		<section>
		<title>rpl_generated</title>
			<para>
			Total number of replies locally generated and relayed by TM module.
			</para>
		</section>

		<section>
		<title>rpl_sent</title>
			<para>
			Total number of replies relayed by TM module.
			</para>
		</section>

	</section>
</chapter>

