<!-- Module User's Guide -->

<chapter>
	<chapterinfo>
	<revhistory>
		<revision>
		<revnumber>$Revision: 1827 $</revnumber>
		<date>$Date: 2007-03-12 17:22:53 +0200 (Mon, 12 Mar 2007) $</date>
		</revision>
	</revhistory>
	</chapterinfo>
	<title>User's Guide</title>
	
	<section>
	<title>Overview</title>
	<para>
		<acronym>TM</acronym> module enables stateful processing of SIP 
		transactions. The main use of stateful logic, which is costly in 
		terms of memory and <acronym>CPU</acronym>, is some services 
		inherently need state. For example, transaction-based accounting 
		(module acc) needs to process transaction state as opposed to 
		individual messages, and any kinds of forking must be implemented 
		statefully. Other use of stateful processing is it trading
		<acronym>CPU</acronym> caused by retransmission processing for memory.
		That makes however only sense if <acronym>CPU</acronym> consumption 
		per request is huge. For example, if you want to avoid costly 
		<acronym>DNS</acronym> resolution for every retransmission of a 
		request to an unresolvable destination, use stateful mode. Then,
		only the initial message burdens server by <acronym>DNS</acronym> 
		queries, subsequent retransmissions will be dropped and will not 
		result in more processes blocked by <acronym>DNS</acronym> resolution.
		The price is more memory consumption and higher processing latency.
	</para>
	<para>
		From user's perspective, the major function is t_relay(). It setup 
		transaction state, absorb retransmissions from upstream, generate 
		downstream retransmissions and correlate replies to requests.
	</para>
	<para>
		In general, if <acronym>TM</acronym> is used, it copies clones of 
		received SIP messages in shared memory. That costs the memory and 
		also <acronym>CPU</acronym> time (memcpys, lookups, shmem locks, etc.)
		Note that non-<acronym>TM</acronym> functions operate over the 
		received message in private memory, that means that any core 
		operations will have no effect on statefully processed messages after 
		creating the transactional state. For example, calling record_route 
		<emphasis>after</emphasis> t_relay is pretty useless, as the 
		<acronym>RR</acronym> is added to privately held message whereas its
		<acronym>TM</acronym> clone is being forwarded.
	</para>
	<para>
		<acronym>TM</acronym> is quite big and uneasy to program--lot of 
		mutexes, shared memory access, malloc & free, timers--you really 
		need to be careful when you do anything. To simplify 
		<acronym>TM</acronym> programming, there is the instrument of 
		callbacks. The callback mechanisms allow programmers to register 
		their functions to specific event. See t_hooks.h for a list of 
		possible events.
	</para>
	<para>
		Other things programmers may want to know is UAC--it is a very 
		simplistic code which allows you to generate your own transactions. 
		Particularly useful for things like NOTIFYs or <acronym>IM</acronym> 
		gateways. The UAC takes care of all the transaction machinery: 
		retransmissions , FR timeouts, forking, etc.  See t_uac prototype 
		in uac.h for more details. Who wants to see the transaction result 
		may register for a callback.
	</para>
	<section id="branch-flags">
		<title>Per-Branch flags</title>
		<para>
		First what is the idea with the branch concept: branch route is a 
		route to be execute separately for each branch before being sent 
		out - changes in that route should reflect only on that branch.
		</para>
		<para>
		There are several types of flags in &ser; :
		</para>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>message/transaction</emphasis> flags - they are 
				visible everywhere in the transaction (in all routes and in 
				all sequential replies/request).
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>branch</emphasis> flags - flags that are visible only
				from a specific branch - in all replies and routes connected 
				to this branch.
			</para>
			<para>
				<emphasis>script</emphasis> flags - flags that exist only
				during script execution. They are not store anywhere and are
				lost once the top level route was left.
			</para>
			</listitem>
			</itemizedlist>
		<para>
		For example: I have a call parallel forking to GW and to a user. And I 
		would like to know from which branch I will get the final negative 
		reply (if so). I will set a branch route before relaying the calls 
		(with the 2 branches). The branch route will be separately executed 
		for each branch; in the branch going to GW (I can identified it by 
		looking to RURI), I will set a branch flag. This flag will appear 
		only in the onreply route run for replied from GW. It will be also be 
		visible in failure route if the final elected reply belongs to the 
		GW branch. This flags will not be visible in the other branch 
		(in routes executing replies from the other branch).
		</para>
		<para>
		For how to define branch flags and use via script, see 
		<xref linkend="branch-route"> and the setbflag(), resetbflag() and
		isbflagset() script functions.
		</para>
		<para>
		Also, modules may set branch flags before transaction creation 
		(for the moment this feature is not available in script). The 
		REGISTRAR module was the first to use this type of flags. The NAT flag 
		is pushed in branch flags instead in message flags
		</para>
	</section>
	<section id="timer-based-failover">
		<title>Timer-Based Failover</title>
		<para>
		Timers can be used to trigger failover behavior. E.g. if we send a call
		a gateway and the gateway does not send a provisional response within 3
		seconds, we want to cancel this call and send the call to another 
		gateway. Another example is to ring a SIP client only for 30 seconds 
		and then redirect the call to the voicemail.
		</para>
		<para>
		There are two timers in &ser; :
		</para>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>fr_timer</emphasis> - this timer is used when
				no response was received yet. If there is no response after
				<emphasis>fr_timer</emphasis> seconds the timer triggers
				(and failure route will be executed if t_on_failure() was
				called). If a provisional response was received, the timer
				is set to fr_inv_timer for INVITE transactions, and RT_T2
				for all other transactions. If a final reponse is received, 
				the transaction has finished.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>fr_inv_timer</emphasis> - this timer is used when 
				a provisional reponse was received for an INVITE transaction.
			</para>
			</listitem>
			</itemizedlist>
		<para>
		For example: You want to have failover if there is no provisional 
		response after 3 seconds, but you want to ring for 60 seconds. 
		Thuse, set the fr_timer to 3 and fr_inv_timer to 60.
		</para>
	</section>
	<section>
		<title>DNS Failover</title>
		<para>
		DNS based failover can be use when relaying stateful requests. 
		According to RFC 3263, DNS failover should be done on transport level
		or transaction level. TM module supports them both.
		</para>
		<para>
		Failover at transport level may be triggered by a failure of sending
		out the request message. A failure occures if the coresponding 
		interface was found for sending the request, if the TCP connection
		was refused ot if a geenric internal error happend during send. There
		is no ICMP error report support.
		</para>
		<para>
		Failover at transaction level may be triggered when the transaction
		completed either with a 503 reply, either with a timeout without
		any received reply. In such a case, automatically, a new branch will
		be forked if any other destination IPs can be used to deliver the 
		requests. The new branch will be a clone of the winning branch.
		</para>
		<para>
		The set of destinations IPs is step-by-step build (on demand) based on
		the NAPTR, SRV and A records available for the destination domain.
		</para>
		<para>
		DNS-based failover is by default applied excepting when this failover
		is globally disabled (see the core parameter disable_dns_failover) or
		when the relay flag (per transaction) is set (see the t_relay()
		function).
		</para>
	</section>
	</section>

	<section>
	<title>Dependencies</title>
	<section>
		<title>&ser; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>No dependencies on other &ser; 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 &ser; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section>
	<title>Exported Parameters</title>
	<section>
		<title><varname>fr_timer</varname> (integer)</title>
		<para>
		Timer which hits if no final reply for a request or ACK for a 
		negative INVITE reply arrives (in seconds).
		</para>
		<para>
		<emphasis>
			Default value is 30 seconds.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>fr_timer</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "fr_timer", 10)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>fr_inv_timer</varname> (integer)</title>
		<para>
		Timer which hits if no final reply for an INVITE arrives after a 
		provisional message was received (in seconds). This timer is started
		after the first provisional response. Thus, fast failover (no 100 
		trying from gateway) can be achieved by setting fr_timer to low 
		values. See example below

		</para>
		<para>
		<emphasis>
			Default value is 120 seconds.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>fr_inv_timer</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "fr_inv_timer", 200)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>wt_timer</varname> (integer)</title>
		<para>
		Time for which a transaction stays in memory to absorb delayed 
		messages after it completed; also, when this timer hits, 
		retransmission of local cancels is stopped (a puristic but complex 
		behavior would be not to enter wait state until local branches
		are finished by a final reply or FR timer--we simplified).
		</para>
		<para>
		<emphasis>
			Default value is 5 seconds.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>wt_timer</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "wt_timer", 10)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>delete_timer</varname> (integer)</title>
		<para>
		Time after which a to-be-deleted transaction currently ref-ed by a
		process will be tried to be deleted again.
		</para>
		<para>
		<emphasis>
			Default value is 2 seconds.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>delete_timer</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "delete_timer", 5)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>T1_timer</varname> (integer)</title>
		<para>
		Retransmission T1 period, in milliseconds.
		</para>
		<para>
		<emphasis>
			Default value is 500 milliseconds.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>T1_timer</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "T1_timer", 700)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>T2_timer</varname> (integer)</title>
		<para>
		Maximum retransmission period, in milliseconds.
		</para>
		<para>
		<emphasis>
			Default value is 4000 milliseconds.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>T2_timer</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "T2_timer", 8000)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>noisy_ctimer</varname> (integer)</title>
		<para>
		If set, on FR timer INVITE transactions will be explicitly canceled 
		if possible, silently dropped otherwise. Preferably, it is turned off 
		to allow very long ringing. This behavior is overridden if a request 
		is forked, or some functionality explicitly turned it off for a 
		transaction (like acc does to avoid unaccounted transactions due to 
		expired timer).
		</para>
		<para>
		<emphasis>
			Default value is 0 (false).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>noisy_ctimer</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "noisy_ctimer", 1)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>ruri_matching</varname> (integer)</title>
		<para>
		Should be request-uri matching used as a part of pre-3261 transaction
		matching as the standard wants us to do so? Turn only off for better 
		interaction with devices that are broken and send different r-uri in
		CANCEL/ACK than in original INVITE.
		</para>
		<para>
		<emphasis>
			Default value is 1 (true).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>ruri_matching</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "ruri_matching", 0)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>via1_matching</varname> (integer)</title>
		<para>
		Should be top most VIA matching used as a part of pre-3261 transaction
		matching as the standard wants us to do so? Turn only off for better 
		interaction with devices that are broken and send different top most
		VIA in CANCEL/ACK than in original INVITE.
		</para>
		<para>
		<emphasis>
			Default value is 1 (true).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>via1_matching</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "via1_matching", 0)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>unix_tx_timeout</varname> (integer)</title>
		<para>
		Send timeout to be used by function which use UNIX sockets 
		(as t_write_unix).
		</para>
		<para>
		<emphasis>
			Default value is 2 seconds.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>unix_tx_timeout</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "unix_tx_timeout", 5)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>restart_fr_on_each_reply</varname> (integer)</title>
		<para>
		If true (non null value), the final response timer will be re-triggered
		for each received provisional reply. In this case, final response
		timeout may occure after a time longe than fr_inv_timer (if UAS keeps
		sending provisional replies)
		</para>
		<para>
		<emphasis>
			Default value is 1 (true).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>restart_fr_on_each_reply</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "restart_fr_on_each_reply", 0)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>fr_timer_avp</varname> (string)</title>
		<para>
		Full specification (NAME, ID, Alias) of an AVP which contains a final
		response timeout value. If present, ths value will overeide the 
		static fr_timer parameter.
		</para>
		<para>
		If set to empty string, the whole mechanism for variable timeout will
		be disabled, falling back to the static value.
		</para>
		<para>
		<emphasis>
			Default value is "NULL" (feature disabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>fr_timer_avp</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "fr_timer_avp", "$avp(i:24)")
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>fr_inv_timer_avp</varname> (string)</title>
		<para>
		Full specification (NAME, ID, Alias) of an AVP which contains a final
		INVITE response timeout value. If present, ths value will overeide the 
		static fr_inv_timer parameter.
		</para>
		<para>
		If set to empty string, the whole mechanism for variable timeout will
		be disabled, falling back to the static value.
		</para>
		<para>
		<emphasis>
			Default value is "NULL" (feature disabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>fr_inv_timer_avp</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "fr_inv_timer_avp", "$avp(i:25)")
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>tw_append</varname> (string)</title>
		<para>
		List of additional information to be appended by t_write_fifo and
		t_write_unix functions.
		</para>
		<para>
		<emphasis>
			Default value is null string.
		</emphasis>
		</para>
		<para>
		Syntax of the parameter is:
		<itemizedlist>
			<listitem><para><emphasis>
			tw_append = append_name':' element (';'element)*
			</emphasis></para></listitem>
			<listitem><para><emphasis>
			element = ( [name '='] pseudo_variable)
			</emphasis></para></listitem>
		</itemizedlist>
		</para>
		<para>
		The full list of supported pseudo-variables in &ser; is availabe at: 
		<ulink url="http://openser.org/docs/pseudo-variables.html-1.1.x">
		http://openser.org/docs/pseudo-variables-1.1.x.html</ulink>
		</para>
		<para>
		Each element will be appended per line in 
		<quote>name: value</quote> format. Element 
		<quote>$rb (message body)</quote>
		is the only one which does not accept name; the body it will be
		printed all the time at the end, disregarding its position in the
		definition string.
		</para>
		<example>
		<title>Set <varname>tw_append</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "tw_append",
   "test: ua=$hdr(User-Agent) ;avp=$avp(i:10);$rb;time=$Ts")
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>pass_provisional_replies</varname> (integer)</title>
		<para>
		Enable/disable passing of provisional replies to FIFO applications.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>pass_provisional_replies</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "pass_provisional_replies", 1)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>syn_branch</varname> (integer)</title>
		<para>
		Enable/disable the usage of stateful synonym branch IDs in the 
		generated Via headers. They are faster but not reboot-safe.
		</para>
		<para>
		<emphasis>
			Default value is 1 (use synonym branches).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>syn_branch</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "syn_branch", 0)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>onreply_avp_mode</varname> (integer)</title>
		<para>
		Describes how the AVPs should be handled in reply route:
		<itemizedlist>
			<listitem><para>
			<emphasis>0</emphasis> - the AVPs will be per message only; they 
			will not interfere with the AVPS stored in transaction; initially
			there will be an empty list and at the end of the route, all AVPs
			that were created will be discarded.
			</para></listitem>
			<listitem><para>
			<emphasis>1</emphasis> - the AVPs will be the transaction AVPs;
			initially the transaction AVPs will be visible; at the end of the
			route, the list will attached back to transaction (with all the 
			changes)
			</para></listitem>
		</itemizedlist>
		</para>
		<para>
		In mode 1, you can see the AVPs yo set in request route, branch route
		or failure route. The side efect is performance as more locking is 
		required in order to keep the AVP's list integrity.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>onreply_avp_mode</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "onreply_avp_mode", 1)
...
</programlisting>
		</example>
	</section>

	</section>


	<section>
	<title>Exported Functions</title>
	<section>
		<title>
		<function moreinfo="none">t_newtran()</function>
		</title>
		<para>
		Creates a new transaction, returns a negative value on error. This is 
		the only way a script can add a new transaction in an atomic way. 
		Typically, it is used to deploy a &uas;.
		</para>
		<warning>
			<para>
			NOTE that the changes on the request that are made after this 
			function call will not be saved into transaction!!!
			</para>
		</warning>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>t_newtran</function> usage</title>
		<programlisting format="linespecific">
...
if (t_newtran()) { 
	log("UAS logic"); 
	t_reply("999","hello"); 
} else sl_reply_error();
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">t_relay([flags])</function>
		</title>
		<para>
		Relay a message statefully to destination indicated in current URI. 
		(If the original URI was rewritten by UsrLoc, RR, strip/prefix, etc., 
		the new URI will be taken). Returns a negative value on failure--you 
		may still want to send a negative reply upstream statelessly not to 
		leave upstream UAC in lurch.
		</para>
		<para>
		The coresponding transaction may or may not be already created. If not
		yet created, the function will automatically create it.
		</para>
		<para>
		The function may take as parameter an optional set of flags for 
		controlling the internal behaviour. The flags may be given in decimal 
		or hexa format; supported flags are:
		</para>
		<itemizedlist>
			<listitem>
				<para><emphasis>0x01</emphasis> - do not generate an 100 trying
				provisional reply when building the transaction. By default 
				one is generated. Useful if you already pushed an 
				stateless 100 reply from script.
				</para>
			</listitem>
			<listitem>
				<para><emphasis>0x02</emphasis> - do not internally send a 
				negative reply in case of failure. It applies only when the
				transaction is created. By default one is sent.
				Useful if you want to implement a serial forking in case of
				failure.
			</listitem>
			<listitem>
				<para><emphasis>0x04</emphasis> - disable the DNS failover
				for the transaction. Only first IP will be used. It disable
				the failover both at transaport and transaction level.
			</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>t_relay</function> usage</title>
		<programlisting format="linespecific">
...
if (!t_relay()) {
    sl_reply_error();
    exit;
}
...
</programlisting>
		</example>
	</section>

	<section id="trelay-1">
		<title>
		<function moreinfo="none">t_relay(proto:host:port,[flags])</function>
		</title>
		<para>
		Relay a message statefully to a fixed destination. The destination is
		specified as <quote>[proto:]host[:port]</quote>.
		</para>
		<para>
		The function may take as parameter an optional set of flags for 
		controlling the internal behaviour - for details see the above 
		<quote>t_relay([flags])</quote> function.
		</para>
		<para>
		This functions can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>t_relay</function> usage</title>
		<programlisting format="linespecific">
...
t_relay("tcp:192.168.1.10:5060");
t_relay("mydomain.com:5070","0x1");
t_relay("udp:mydomain.com");
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">t_reply(code, reason_phrase)</function>
		</title>
		<para>
		Sends a stateful reply after a transaction has been established. See
		<function>t_newtran</function> for usage.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>code</emphasis> - Reply code number.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>reason_phrase</emphasis> - Reason string.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>t_reply</function> usage</title>
		<programlisting format="linespecific">
...
t_reply("404", "Not found");
...
</programlisting>
		</example>
	</section>

	<section id="treplicate">
		<title>
		<function moreinfo="none">t_replicate(URI,[flags])</function>
		</title>
		<para>
		Replicates a request to another destination. No information due the
		replicated request (like reply code) will be forwarded to the 
		original SIP UAC.
		</para>
		<para>
		The destination is specified by a SIP URI. If multiple destinations are
		to be used, the additional SIP URIs have to be set as branches.
		</para>
		<para>
		The function may take as parameter an optional set of flags for 
		controlling the internal behaviour - for description see the above 
		<quote>t_relay([flags])</quote> function. Note that only 0x4 is 
		applicable here.
		</para>
		<para>
		This functions can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>t_replicate</function> usage</title>
		<programlisting format="linespecific">
...
t_replicate("sip:1.2.3.4:5060");
t_replicate("sip:1.2.3.4:5060;transport=tcp");
t_replicate("sip:1.2.3.4","0x4");
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">t_release()</function>
		</title>
		<para>
		Remove transaction from memory (it will be first put on a wait timer 
		to absorb delayed messages).
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>t_release</function> usage</title>
		<programlisting format="linespecific">
...
t_release();
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">t_check_status(re)</function>
		</title>
		<para>
		Returns true if the regualr expresion <quote>re</quote> match the 
		reply code of the response message as follows:
		<itemizedlist>
		<listitem>
			<para><emphasis>in routing block</emphasis> - the code of the
			last sent reply.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>in on_reply block</emphasis> - the code of the
			current received reply.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>in on_failure block</emphasis> - the code of the
			selected negative final reply.
			</para>
		</listitem>
		</itemizedlist>
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE and BRANCH_ROUTE .
		</para>
		<example>
		<title><function>t_check_status</function> usage</title>
		<programlisting format="linespecific">
...
if (t_check_status("(487)|(408)")) {
    log("487 or 408 negative reply\n");
}
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">t_flush_flags()</function>
		</title>
		<para>
		Flush the flags from current request into the already created 
		transaction. It make sens only in routing block if the trnasaction was
		created via t_newtran() and the flags have been altered since.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE and BRANCH_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_local_replied(reply)</function>
		</title>
		<para>
		Returns true if all or last (depending of the parameter) reply(es) were
		local generated (and not received).
		</para>
		<para>
		Parameter may be <quote>all</quote> or <quote>last</quote>.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, BRANCH_ROUTE,
		FAILURE_ROUTE and ONREPLY_ROUTE.
		</para>
		<example>
		<title><function>t_local_replied</function> usage</title>
		<programlisting format="linespecific">
...
if (t_local_replied("all")) {
	log ("no reply received\n");
}
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">t_write_fifo(info,fifo)</function>
		<function moreinfo="none">t_write_unix(info,sock)</function>
		</title>
		<para>
		Write via FIFO file or UNIX socket a lot of information regarding the
		request. Which information should be written may be control via the
		<quote>tw_append</quote> parameter.
		</para>
		<para>
		This functions can be used from REQUEST_ROUTE, FAILURE_ROUTE and 
		BRANCH_ROUTE.
		</para>
		<example>
		<title><function>t_write_fifo/unix</function> usage</title>
		<programlisting format="linespecific">
...
modparam("tm","tw_append","append1:Email=avp[i:12];UA=hdr[User-Agent]")
modparam("tm","tw_append","append2:body=msg[body]")
...
t_write_fifo("voicemail/append1","/tmp/appx_fifo");
...
t_write_unix("logger/append2","/var/run/logger.sock");
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">t_check_trans()</function>
		</title>
		<para>
		Returns true if the current request is associated to a transaction. 
		The relationship between the request ans transaction is defined as 
		follow:
		</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>non-CANCEL/non-ACK requests</emphasis> - is true 
			if the request belongs to a transaction; if so, it means that the 
			request is a retransmision.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>CANCEL request</emphasis> - true if the cancelled
			INVITE transaction exists.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>ACK request</emphasis> - true if the ACK is a
			local end-to-end ACK for an existent INVITE transaction.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE and BRANCH_ROUTE.
		</para>
		<example>
		<title><function>t_check_trans</function> usage</title>
		<programlisting format="linespecific">
...
if ( is_method("CANCEL") ) {
	if ( t_check_trans() )
		t_relay();
	exit;
}
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">t_was_cancelled()</function>
		</title>
		<para>
		Retuns true if called for an INVITE transaction that was explicitly
		cancelled by UAC side via a CANCEL request.
		</para>
		<para>
		This function can be used from ONREPLY_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>t_was_cancelled</function> usage</title>
		<programlisting format="linespecific">
...
if (t_was_cancelled()) {
    log("transaction was cancelled by UAC\n");
}
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">t_on_failure(failure_route)</function>
		</title>
		<para>
		Sets reply routing block, to which control is passed after a 
		transaction completed with a negative result but before sending a 
		final reply. In the referred block, you can either start a new branch 
		(good for services such as forward_on_no_reply) or send a final reply 
		on your own (good for example for message silo, which received a 
		negative reply from upstream and wants to tell upstream <quote>202 I 
		will take care of it</quote>).
		</para>
		<para>
		As not all functions are available from failure route, please check 
		the documentation for each function to see the permissions.
		Any other commands may result in unpredictable behavior and 
		possible server failure.
		</para>
		<para>
		Only one failure_route can be armed for a request. If you use many
		times t_on_failure(), only the last one has effect.
		</para>
		<para>
		Note that whenever failure_route is entered, RURI is set to value 
		of the winning branch.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>failure_route</emphasis> - Reply route block to be 
			called.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, BRANCH_ROUTE, 
		ONREPLY_ROUTE and FAILURE_ROUTE.
		</para>
		<example>
		<title><function>t_on_failure</function> usage</title>
		<programlisting format="linespecific">
...
route { 
	t_on_failure("1"); 
	t_relay();
} 

failure_route[1] {
	seturi("sip:user@voicemail");
	append_branch();
	t_relay();
}
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">t_on_reply(reply_route)</function>
		</title>
		<para>
		Sets reply routing block, to which control is passed each time a reply
		(provisional or final) for the transaction is received. 
		The route is not called for local generated replies! In the referred 
		block, you can inspect the reply and perform text operations on it.
		</para>
		<para>
		As not all functions are available from this type of route, please 
		check  the documentation for each function to see the permissions.
		Any other commands may result in unpredictable behavior and 
		possible server failure.
		</para>
		<para>
		Only one onreply_route can be armed for a request. If you use many
		times t_on_reply(), only the last one has effect.
		</para>
		<para>
		If the processed reply is provisionla reply (1xx code), by calling
		the drop() function (exported by core), the execution of the route
		will end and the reply will not be forwarded further.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>reply_route</emphasis> - Reply route block to be 
			called.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, BRANCH_ROUTE, 
		ONREPLY_ROUTE and FAILURE_ROUTE.
		</para>
		<example>
		<title><function>t_on_reply</function> usage</title>
		<programlisting format="linespecific">
...
route { 
	t_on_reply("1"); 
	t_relay();
} 

onreply_route[1] {
	if (t_check_status("1[0-9][0-9]")) {
		setflag(1);
		log("provisional reply received\n");
		if (t_check_status("183"))
			drop;
	}
}
...
</programlisting>
		</example>
	</section>

	<section id="branch-route">
		<title>
		<function moreinfo="none">t_on_branch(branch_route)</function>
		</title>
		<para>
		Sets a branch route to be execute separately for each branch of the
		transaction before being sent out - changes in that route should 
		reflect only on that branch.
		</para>
		<para>
		As not all functions are available from this type of route, please 
		check  the documentation for each function to see the permissions.
		Any other commands may result in unpredictable behavior and 
		possible server failure.
		</para>
		<para>
		Only one branch_route can be armed for a request. If you use many
		time t_on_branch(), only the last one has effect.
		</para>
		<para>
		By calling the drop() function (exported by core), the execution of 
		the branch route will end and the branch will not be forwarded further.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>branch_route</emphasis> - Branch route block to be 
			called.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, BRANCH_ROUTE, 
		ONREPLY_ROUTE and FAILURE_ROUTE.
		</para>
		<example>
		<title><function>t_on_branch</function> usage</title>
		<programlisting format="linespecific">
...
route { 
	t_on_reply("1"); 
	t_relay();
} 

branch_route[1] {
	if (uri=~"bad_uri") {
		xlog("dropping branch $ru \n");
		drop;
	}
	if (uri=~"GW_uri") {
		append_rpid();
	}
}
...
</programlisting>
		</example>
	</section>

	</section>


	<section>
		<title>Exported pseudo-variables</title>
		<para>
		Exported pseudo-variables are listed in the next sections.
		</para>
		<section>
		<title>$T_branch_idx</title>
			<para>
			<emphasis>$T_branch_idx</emphasis> - the index (starting with 1
			for the first branch) of the branch for which is executed the
			branch_route[]. If used outside of branch_route[] block, the value
			is '0'.
			</para>
		</section>
		<section>
		<title>$T_reply_code</title>
			<para>
			<emphasis>$T_reply_code</emphasis> - the code of the reply, as 
			follows: in request_route will be the last stateful sent reply;
			in reply_route will be the current processed reply; in 
			failure_route will be the negative winning reply. In case of 
			no-reply or error, '0' value is returned.
			</para>
		</section>
	</section>


	<section>
	<title>Exported MI Functions</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_uac_cancel</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
			</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>Exported statistics</title>
		<para>
		Exported statistics are listed in the next sections.
		</para>
		<section>
		<title>received_replies</title>
			<para>
			Total number of total replies received by TM module - can be
			resetted.
			</para>
		</section>
		<section>
		<title>relayed_replies</title>
			<para>
			Total number of replied received and relayed by TM module - can be
			resetted.
			</para>
		</section>
		<section>
		<title>local_replies</title>
			<para>
			Total number of replied local generated by TM module - can be
			resetted.
			</para>
		</section>
		<section>
		<title>UAS_transactions</title>
			<para>
			Total number of transaction created by received requests - can be
			resetted.
			</para>
		</section>
		<section>
		<title>UAC_transactions</title>
			<para>
			Total number of transaction created by local generated requests - 
			can be resetted.
			</para>
		</section>
		<section>
		<title>2xx_transactions</title>
			<para>
			Total number of transaction completed with 2xx replies - 
			can be resetted.
			</para>
		</section>
		<section>
		<title>3xx_transactions</title>
			<para>
			Total number of transaction completed with 3xx replies - 
			can be resetted.
			</para>
		</section>
		<section>
		<title>4xx_transactions</title>
			<para>
			Total number of transaction completed with 4xx replies - 
			can be resetted.
			</para>
		</section>
		<section>
		<title>5xx_transactions</title>
			<para>
			Total number of transaction completed with 5xx replies - 
			can be resetted.
			</para>
		</section>
		<section>
		<title>6xx_transactions</title>
			<para>
			Total number of transaction completed with 6xx replies - 
			can be resetted.
			</para>
		</section>
		<section>
		<title>inuse_transactions</title>
			<para>
			Number of transaction existing in memeory at current time - 
			can not be resetted.
			</para>
		</section>
	</section>

</chapter>

<!-- Keep this element at the end of the file
Local Variables:
sgml-parent-document: ("tm.sgml" "Book" "chapter")
End:
-->
