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

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<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 and 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 &osips; :
		</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>
			</listitem>
			<listitem>
			<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="func_t_on_branch"/> 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>Timeout-Based Failover</title>
		<para>
		Timeouts can be used to trigger failover behavior. E.g. if we send a call
		to 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>
		The transaction module exports two types of timeouts:
		</para>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis role='bold'><xref linkend="param_fr_timeout"/></emphasis> - used when no response was
				received yet. If there is no response after
				<emphasis><xref linkend="param_fr_timeout"/></emphasis> seconds, the timer triggers
				(and failure route will be executed if t_on_failure() was
				called). For INVITE transactions, if a provisional response was
				received, the timeout is reset to <emphasis><xref linkend="param_fr_inv_timeout"/></emphasis>
				seconds and RT_T2 for all other transactions. Once a final response
				is received, the transaction has finished.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis role='bold'>fr_inv_timeout</emphasis> - this timeout
				starts counting down once a provisional response 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. 
		Thus, set the <emphasis><xref linkend="param_fr_timeout"/></emphasis> to 3 and 
		<emphasis>fr_inv_timeout</emphasis> 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 occurs if the corresponding 
		interface was found for sending the request, if the TCP connection
		was refused or if a generic internal error happened 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 id='tm_anycast' xreflabel='tm_anycast'>
		<title>Anycast Scenario</title>
		<para>
		Doing a load balancing scenario using
		<ulink url='https://en.wikipedia.org/wiki/Anycast'>Anycast IPs</ulink>,
		one might run into an issue where a transaction request comes on
		one instance, and the reply (or replies) comes on different ones.
		This would normaly break the transaction state, because the local
		transaction will start re-transmissios and would eventually timeout.
		Moreover, from UA's perspective, the reply whould have been sent,
		but since it reaches a proxy that is not aware of that transaction,
		it will not be forwarded (nor ACKed in case of INVITES). And from
		this point things can escalade quickly.
		</para>
		<para>
		To sort out these problems, the module uses a distributed mechanism
		to figure out where the transaction for a specific reply was created.
		When an instance receives a reply that does not have an associated
		transaction, it replicates it to be handled by the instance that
		<quote>owns</quote> it. This is achieved using the
		<emphasis>clusterer</emphasis> module support.
		</para>
		<para>
		Setting up an anycast scenario is very simple: all the instances
		that are part of an anycast secnario must be set up in a cluster
		(more info at the <xref linkend="param_tm_replication_cluster"/> param).
		When a transaction is created, a special identifier is appended to
		the branch parameter, namely the instance that created the
		transaction. When a reply comes in, the transaction module checks who
		<quote>owns</quote> the transaction. If the identifier is the
		instance's own id, then the reply is processed locally. Otherwise
		it is replicated to the node indicated by the id. Replication is
		done in a very efficient manner, using the
		<emphasis>proto_bin</emphasis> transport.
		</para>
		<para>
		Special handling is applied to <emphasis>CANCEL</emphasis> and
		<emphasis>ACK</emphasis> methods. Due to the fact that these
		methods do not contain the special identifier in the branch
		parameter (since they are generated by the UAC and not by us),
		there is no way to determine who <quote>owns</quote> the transaction.
		Therefore, if we do not find a local transaction for these
		requests, we broadcast them to all the other instances using
		the <xref linkend="func_t_anycast_replicate"/> function. Again,
		this is done in a very efficient manner using the
		<emphasis>proto_bin</emphasis> transport.
		</para>
	</section>
	<section>
		<title>Usage Scope</title>
		<para>
		Transaction functions and variables are only designed to be
		called on SIP request messages where a transaction can be created, or
		in routes that are transaction aware, such as
		<emphasis>branch_route[name]</emphasis>,
		<emphasis>failure_route[name]</emphasis> or
		<emphasis>onreply_route[name]</emphasis>. Using TM functtions or
		variables in a route that is not transaction aware, such as
		the generic <emphasis>onreply_route</emphasis>,
		<emphasis>error_route</emphasis> or
		<emphasis>timer_route[name, timer]</emphasis> may lead to undefined
		behavior, and most of the time in bogus or malformed signalling.
		Therefore it is strongly recommended to avoid using them in non-tm
		context aware routes.
		</para>
	</section>
	</section>

	<section id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section>
		<title>&osips; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>clusterer</emphasis> module, if the anycast
				scenario is enabled (see <xref linkend="param_tm_replication_cluster"/>
				param for more information).
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before 
		running &osips; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>
	<section id="param_fr_timeout" xreflabel="fr_timeout">
		<title><varname>fr_timeout</varname> (integer)</title>
		<para>
		Timeout which is triggered 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_timeout</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "fr_timeout", 10)
...
</programlisting>
		</example>
	</section>

	<section id="param_fr_inv_timeout" xreflabel="fr_inv_timeout">
		<title><varname>fr_inv_timeout</varname> (integer)</title>
		<para>
		Timeout which is triggered if no final reply for an INVITE arrives after a 
		provisional message was received (in seconds). This timeout starts
		counting down once the first provisional response is received. Thus,
		fast failover (no 100 trying from gateway) can be achieved by setting
		<emphasis><xref linkend="param_fr_timeout"/></emphasis> to low values.
		See example below.
		</para>
		<para>
		<emphasis>
			Default value is 120 seconds.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>fr_inv_timeout</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "fr_inv_timeout", 200)
...
</programlisting>
		</example>
	</section>

	<section id="param_wt_timer" xreflabel="wt_timer">
		<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>
		For non-INVITE transaction this timer relates to timer J of RFC 3261 
		section 17.2.2. According to the RFC this timer should be 64*T1 
		(= 32 seconds). But this would increase memory usage as the transactions
		are kept in memory very long.
		</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 id="param_delete_timer" xreflabel="delete_timer">
		<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 id="param_T1_timer" xreflabel="T1_timer">
		<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 id="param_T2_timer" xreflabel="T2_timer">
		<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 id="param_ruri_matching" xreflabel="ruri_matching">
		<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 id="param_via1_matching" xreflabel="via1_matching">
		<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 id="param_unix_tx_timeout" xreflabel="unix_tx_timeout">
		<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 id="param_restart_fr_on_each_reply" xreflabel="restart_fr_on_each_reply">
		<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 occur after a time longer than <emphasis><xref linkend="param_fr_inv_timeout"/></emphasis>
		(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 id="param_tw_append" xreflabel="tw_append">
		<title><varname>tw_append</varname> (string)</title>
		<para>
		List of additional information to be appended by t_write_req 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 '='] variable)
			</emphasis></para></listitem>
		</itemizedlist>
		</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(avp);$rb;time=$Ts")
...
</programlisting>
		</example>
	</section>

	<section id="param_pass_provisional_replies" xreflabel="pass_provisional_replies">
		<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 id="param_syn_branch" xreflabel="syn_branch">
		<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 id="param_onreply_avp_mode" xreflabel="onreply_avp_mode">
		<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 you set in request route, branch route
		or failure route. The side effect 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 id="param_disable_6xx_block" xreflabel="disable_6xx_block">
		<title><varname>disable_6xx_block</varname> (integer)</title>
		<para>
		Tells how the 6xx replies should be internally handled:
		<itemizedlist>
			<listitem><para>
			<emphasis>0</emphasis> - the 6xx replies will block any further
			serial forking (adding new branches). This is the RFC3261
			behaviour.
			</para></listitem>
			<listitem><para>
			<emphasis>1</emphasis> - the 6xx replies will be handled as any
			other negative reply - serial forking will be allowed.
			Logically, you need to break RFC3261 if you want to do redirects
			to announcement and voicemail services.
			</para></listitem>
		</itemizedlist>
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>disable_6xx_block</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "disable_6xx_block", 1)
...
</programlisting>
		</example>
	</section>

	<section id="param_enable_stats" xreflabel="enable_stats">
		<title><varname>enable_stats</varname> (integer)</title>
		<para>
		Enables statistics support in TM module - If enabled, the TM module
		will internally keep several statistics and export them via the 
		MI - Management Interface.
		</para>
		<para>
		<emphasis>
			Default value is 1 (enabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>enable_stats</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "enable_stats", 0)
...
</programlisting>
		</example>
	</section>

	<section id="param_minor_branch_flag" xreflabel="minor_branch_flag">
		<title><varname>minor_branch_flag</varname> (string/integer)</title>
		<para>
		A branch flag index to be used in script to mark the minor branches 
		( before t_relay() ).
		</para>
		<para>
		A minor branch is a branch OpenSIPS will not wait to complete during
		parallel forking. So, if the rest of the branches are negativly replied
		OpenSIPS will not wait for a final answer from the minor branch, but
		it will simply cancel it.
		</para>
		<para>
		Main applicability of minor branch is to fork a branch to a media 
		server for injecting (via 183 Early Media) some pre-call media - of
		course, this branch will be transparanent for the rest of the call
		branches (from branch selection point of view).
		</para>
		<para>
		<emphasis>
			Default value is none (disabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>minor_branch_flag</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "minor_branch_flag", "MINOR_BFLAG")
...
</programlisting>
		</example>
	</section>

	<section id="param_timer_partitions" xreflabel="timer_partitions">
		<title><varname>timer_partitions</varname> (integer)</title>
		<para>
		The number of partitions for the internal TM timers (retransmissions,
		delete, wait, etc). Partitioning the timers increase the throughput
		under heavly load by handling timer events in parallel, rather than
		all serial.
		</para>
		<para>
		Recomanded range for timer partitions is max 16 (soft limit).
		</para>
		<para>
		<emphasis>
			Default value is 1 (disabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>timer_partitions</varname> parameter</title>
		<programlisting format="linespecific">
...
# Enable two timer partitions
modparam("tm", "timer_partitions", 2)
...
</programlisting>
		</example>
	</section>

	<section id="param_auto_100trying" xreflabel="auto_100trying">
		<title><varname>auto_100trying</varname> (integer)</title>
		<para>
		This parameter controls if the TM module should automatically 
		generate an 100 Trying stateful reply when an INVITE transaction
		is created.
		</para>
		<para>
		You may want to disable this behavior if you want to control from
		script level when the 100 Trying is to be sent out.
		</para>
		<para>
		<emphasis>
			Default value is 1 (enabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>auto_100trying</varname> parameter</title>
		<programlisting format="linespecific">
...
# Disable automatic 100 Trying
modparam("tm", "auto_100trying", 0)
...
</programlisting>
		</example>
	</section>

	<section id="param_tm_replication_cluster" xreflabel="tm_replication_cluster">
		<title><varname>tm_replication_cluster</varname> (integer)</title>
		<para>
		This parameter should be used in an anycast setup, and specifies
		the cluster id of all the nodes that use an anycast IP.
		</para>
		<para>
		Check out the <xref linkend="tm_anycast"/> section for more details.
		</para>
		<para>
		<emphasis>
			Anycast replication is disabled by default.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>tm_replication_cluster</varname> parameter</title>
		<programlisting format="linespecific">
...
# replicate anycast messages in cluster 1
modparam("tm", "tm_replication_cluster", 1)
...
</programlisting>
		</example>
	</section>

	<section id="param_cluster_param" xreflabel="cluster_param">
		<title><varname>cluster_param</varname> (string)</title>
		<para>
		This parameter should be used in an anycast setup, and specifies
		the name of the parameter used in the VIA branch param to specifiy
		the instance id that created the transaction.
		</para>
		<para>
		Check out the <xref linkend="tm_anycast"/> section for more details.
		</para>
		<para>
		<emphasis>
			Default value is <emphasis>cid</emphasis>.
		</emphasis>
		</para>
		<example>
		<title>Set the <varname>cluster_param</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "cluster_param", "tid")
...
</programlisting>
		</example>
	</section>

	<section id="param_cluster_auto_cancel" xreflabel="cluster_auto_cancel">
		<title><varname>cluster_auto_cancel</varname> (boolean)</title>
		<para>
		This parameter should be used in an anycast setup, and specifies
		whether a <emphasis>CANCEL</emphasis> message received on a
		listener that is marked as anycast should be automatically handled,
		or should get in the &osips; script. If this parameter is enabled
		(default), <emphasis>CANCEL</emphasis> messages received on an
		anycast listener will never enter the script, thus making the
		script cleaner.
		</para>
		<para>
		Check out the <xref linkend="tm_anycast"/> section for more details.
		</para>
		<para>
		<emphasis>
			Default value is <emphasis>yes</emphasis> (enabled).
		</emphasis>
		</para>
		<example>
		<title>Set the <varname>cluster_auto_cancel</varname> parameter</title>
		<programlisting format="linespecific">
...
# disable auto-cancel handling
modparam("tm", "cluster_auto_cancel", no)
...
</programlisting>
		</example>
	</section>

	<section id="param_local_request_route" xreflabel="local_request_route">
		<title><varname>local_request_route</varname> (string)</title>
		<para>
		This parameter points to a route, which is executed whenever TM is
		about to send out a locally generated request (e.g., through the 
		B2B modules or through MI).
		</para>
		<para>
		The purpose of this route is limited to exposing the content of the 
		request as SIP message 
		</para>
		<para>
		The route is executed with the generated message by TM, incorporating
		all modifications.
		</para>
		<para>
		IMPORTANT: this route is executed AFTER the local_route (if defined)
		and it expose all the changes from that route.
		</para>
		<para>
		IMPORTANT: this route is to be used in a read-only manner, inspection
		only. Any changes you do here will discarded.
		</para>
		<para>
		IMPORTANT: this route does not offer any message, transactional or
		dialog context, so do not rely on any variables with scope (like AVPs).
		</para>
		<example>
		<title>Set the <varname>local_request_route</varname> parameter</title>
		<programlisting format="linespecific">
...
# Execute the route "local_request_route" upon sending a request
modparam("tm", "local_request_route", "tm_local_request")

route[tm_local_request] {
	if (is_method("INVITE") &amp;&amp; $rb(application/sdp) &amp;&amp; !has_totag()) {
		$avp(sdp_request) := $rb(application/sdp);
	}
}
...
</programlisting>
		</example>
	</section>

	<section id="param_local_reply_route" xreflabel="local_reply_route">
		<title><varname>local_reply_route</varname> (string)</title>
		<para>
		This parameter points to a route, which is executed whenever TM is
		about to send out a locally generated reply (e.g., through the 
		B2B modules or through MI).
		</para>
		<para>
		The purpose of this route is limited to exposing the content of the 
		reply as SIP message 
		</para>
		<para>
		IMPORTANT: this route is to be used in a read-only manner, inspection
		only. Any changes you do here will discarded.
		</para>
		<para>
		IMPORTANT: this route does not offer any message, transactional or
		dialog context, so do not rely on any variables with scope (like AVPs).
		</para>
		<example>
		<title>Set the <varname>local_reply_route</varname> parameter</title>
		<programlisting format="linespecific">
...
# Execute the route "tm_local_reply" upon sending a request
modparam("tm", "local_reply_route", "tm_local_reply")

route[tm_local_reply] {
	if (is_method("BYE")) {
		$var(rc) = rest_get("http://localhost/qos/delete",
					$var(recv_body), $var(recv_ct), $var(rcode));
	}
}

...
</programlisting>
		</example>
	</section>

	</section>


	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	<section id="func_t_relay" xreflabel="t_relay()">
		<title>
		<function moreinfo="none">t_relay([flags],[outbound_proxy])</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 two optional parameters.
		</para>
		<para>
		The first parameter is a comma separated list of string flags for
		controlling the internal behaviour. The supported flags are:
		</para>
		<itemizedlist>
			<listitem>
				<para><emphasis>no-auto-477</emphasis> - (old
				<emphasis>0x02</emphasis> flag) do not internally generate
				and send a "477 Send failed (477/TM)" SIP reply in case of a
				global forwarding failure (i.e. forwarding for each branch has
				failed due to internal errors, bad R-URI, bad message, lack of
				network reachability, etc.).
				<para>
				</para>
				This flag only applies if the transaction was
				not previously created by <xref linkend="func_t_newtran"/>.
				When a global forwarding failure occurs, no SIP request is
				relayed and therefore no negative SIP reply or timeout will
				show up on the failure_route, if one is set.
				</para>
				<para>
				Useful if you want to implement a failover logic for when none
				of the currently created branches can be forwarded to.
				</para>
			</listitem>
			<listitem>
				<para><emphasis>no-dns-failover</emphasis> - (old
				<emphasis>0x04</emphasis> flag) disable the DNS failover
				for the transaction. Only first IP will be used. It disables
				the failover both at transport and transaction level.
				</para>
			</listitem>
			<listitem>
				<para><emphasis>pass-reason-hdr</emphasis> - (old
				<emphasis>0x08</emphasis> flag) If the request is a CANCEL,
				trust and pass further the Reason header from the received
				CANCEL - shortly, will propagate the Reason header.
				</para>
			</listitem>
			<listitem>
				<para><emphasis>allow-no-cancel</emphasis> - (old
				<emphasis>0x10</emphasis> flag) Allows OpenSIPS to inspect
				and follow the Content-Disposition "no-cancel" indication (if
				present). As per RFC3841, section 9.1, the TM module may be 
				instructed not to cancel all ongoing branches when a 2xx reply
				is received. It will keep the pending branches ongoing until
				(1) all branches will receive a final reply or (2) the 
				transactionhits the timeout.
				</para>
			</listitem>

		</itemizedlist>
		<para>
		The second parameter is a string representing an outbound proxy
		(a fixed destination) where the message should be sent. The
		destination is specified as <quote>[proto:]host[:port]</quote>. If a 
		destination URI <quote>$du</quote> for this message was set before the
		function is called then this value will be used as the destination 
		instead of the function parameter.
		</para>
		<para>
		In case of error, the function returns the following codes:
		</para>
		<itemizedlist>
			<listitem>
				<para><emphasis>-1</emphasis> - generic internal error
				</para>
			</listitem>
			<listitem>
				<para><emphasis>-2</emphasis> - bad message (parsing errors)
				</para>
			</listitem>
			<listitem>
				<para><emphasis>-3</emphasis> - no destination available 
				(no branches were added or request already cancelled)
				</para>
			</listitem>
			<listitem>
				<para><emphasis>-4</emphasis> - bad destination 
				(unresolvable address)
				</para>
			</listitem>
			<listitem>
				<para><emphasis>-5</emphasis> - destination filtered 
				(black listed)
				</para>
			</listitem>
			<listitem>
				<para><emphasis>-6</emphasis> - generic send failed
				</para>
			</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;
}
...
t_relay( ,"tcp:192.168.1.10:5060");
...
t_relay(0x1, "mydomain.com:5070");
...
</programlisting>
		</example>
	</section>

	<section id="func_t_reply" xreflabel="t_reply()">
		<title>
		<function moreinfo="none">t_reply(code, reason_phrase)</function>
		</title>
		<para>
		Sends a stateful SIP reply to the currently processed requests. Note 
		that if the transaction was not created yet, it will automatically
		created by internally using the
		<function>t_newtran</function> function.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>code (int)</emphasis> - Reply code number.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>reason_phrase (string)</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, "Use $rU not found");
...
</programlisting>
		</example>
	</section>

	<section id="func_t_reply_with_body" xreflabel="t_reply_with_body()">
		<title>
		<function moreinfo="none">t_reply_with_body(code, reason_phrase, body)</function>
		</title>
		<para>
		Sends a stateful SIP reply with a body to the currently processed 
		requests. Note that if the transaction was not created yet, it will 
		automatically created by internally using the
		<function>t_newtran</function> function.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>code (int)</emphasis> - Reply code number.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>reason_phrase (string)</emphasis> - Reason string.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>body (string)</emphasis> - Reply body.
			</para>
		</listitem>
		</itemizedlist>

		<para>
		This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
		</para>
		<example>
		<title><function>t_reply_with_body</function> usage</title>
		<programlisting format="linespecific">
...
	if(is_method("INVITE"))
	{
		append_to_reply("Contact: $var(contact)\r\n"
				"Content-Type: application/sdp\r\n");
		t_reply_with_body(200, "Ok", $var(body));
		exit;
	}
...
</programlisting>
		</example>
	</section>

	<section id="func_t_newtran" xreflabel="t_newtran()">
		<title>
		<function moreinfo="none">t_newtran()</function>
		</title>
		<para>
		Creates the SIP transaction for the currently processed SIP request,
		thus switching to stateful processing.  For INVITE requests, a 100
		Trying reply will be immediately sent, unless
		<xref linkend="param_auto_100trying"/> is disabled.  Once a SIP
		transaction is created, calling <xref linkend="func_t_newtran"/> for
		retransmitted requests will end the OpenSIPS script execution, with the
		lastly sent reply being retransmitted upstream.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>t_newtran</function> usage</title>
		<programlisting format="linespecific">
...
t_newtran();  # 100 Trying is fired here
xlog("doing my complicated routing logic\n");
....
t_relay(); # send the call further
...
</programlisting>
		</example>
	</section>

	<section id="func_t_check_trans" xreflabel="t_check_trans()">
		<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 and transaction is defined as
		follows:
		</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>non-CANCEL/non-ACK requests</emphasis> - if the
			request belongs to a transaction (it's a retransmision), the
			function will do a standard processing of the retransmission and
			will break/stop the script. The function returns false if the
			request is not a retransmission.
			</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
			hop-by-hop ACK (to a negative reply) corresponding to an previous
			INVITE transaction. IMPORTANT: this function returns false (return
			code <emphasis>-2</emphasis>) for end-to-end ACKs (to 2xx replies
			from a different transaction).
			</para>
		</listitem>
		</itemizedlist>
		<para>
		Note: To detect retransmissions using this function you have to make 
		sure that the initial request has already created a transaction, e.g. 
		by using t_relay(). If the processing of requests may take long time 
		(e.g. DB lookups) and the retransmission arrives before t_relay() is 
		called, you can use the t_newtran() function to manually create a 
		transaction.
		</para>
		<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 id="func_t_check_status" xreflabel="t_check_status()">
		<title>
		<function moreinfo="none">t_check_status(re)</function>
		</title>
		<para>
		Returns true if the regualr expression <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 id="func_t_local_replied" xreflabel="t_local_replied()">
		<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 id="func_t_was_cancelled" xreflabel="t_was_cancelled()">
		<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 id="func_t_cancel_branch" xreflabel="t_cancel_branch()">
		<title>
		<function moreinfo="none">t_cancel_branch([flags])</function>
		</title>
		<para>
		This function is to be call when a reply is received for cancelling a
		set of branches (see flags) of the current call.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>flags (string, optional)</emphasis> - set of flags 
			(char based flags) to control what branches to be cancelled:
			</para>
			<itemizedlist>
			<listitem>
				<para><emphasis>a</emphasis> - all - cancel all pending 
				branches
				</para>
			</listitem>
			<listitem>
				<para><emphasis>o</emphasis> - others - cancel all the other
				pending branches except the current one
				</para>
			</listitem>
			<listitem>
				<para><emphasis>empty</emphasis> - current - cancel only the
				current branch
				</para>
			</listitem>
			</itemizedlist>
		</listitem>
		</itemizedlist>

		<para>
		This function can be used from ONREPLY_ROUTE.
		</para>
		<example>
		<title><function>t_cancel_branch</function> usage</title>
		<programlisting format="linespecific">
onreply_route[3] {
...
	if (t_check_status(183)) {
		# no support for early media
		t_cancel_branch();
	}
...
}
</programlisting>
		</example>
	</section>

	<section id="func_t_new_request" xreflabel="t_new_request()">
		<title>
		<function moreinfo="none">t_new_request(method,RURI,from,to[,body[,ctx]])</function>
		</title>
		<para>
		This function generates and sends out a new SIP request (in a stateful way).
		The new request is completly unrelated to the currently processed SIP message.
		</para>
		<para>Meaning of the parameters is as follows (all do accept variables):</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>method (string)</emphasis> - the SIP method
			</para>
		</listitem>
		<listitem>
			<para><emphasis>RURI (string)</emphasis> - the SIP Request URI (the request 
			will be sent out to this destination)
			</para>
		</listitem>
		<listitem>
			<para><emphasis>from (string)</emphasis> - the SIP From hdr information as
			"[display ]URI"
			</para>
		</listitem>
		<listitem>
			<para><emphasis>to (string)</emphasis> - the SIP To hdr information as
			"[display ]URI"
			</para>
		</listitem>
		<listitem>
			<para><emphasis>body (string, optional)</emphasis> - the SIP body content
			starting with the content type string: "conten_type body"
			</para>
		</listitem>
		<listitem>
			<para><emphasis>ctx (string, optional)</emphasis> - a context string that will
			be added to the new transaction as an AVP with name "uac_ctx" (it may be visible
			in local route)
			</para>
		</listitem>
		</itemizedlist>

		<example>
		<title><function>t_new_request</function> usage</title>
		<programlisting format="linespecific">
...
	# send a MESSAGE request
	t_new_request("MESSAGE","sip:alice@192.168.2.2","BOB sip:userB@mydomain.net","ALICE sip:userA@mydomain.net","text/plain Hello Alice!")) {
...
</programlisting>
		</example>
	</section>

	<section id="func_t_on_failure" xreflabel="t_on_failure()">
		<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 (string)</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");
	t_relay();
}
...
</programlisting>
		</example>
	</section>

	<section id="func_t_on_reply" xreflabel="t_on_reply()">
		<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>
		If called from branch route, the reply route will be set only for the
		current branch - that's it, it will be called only for relies belonging
		to that particular branch. Of course, from branch route, you can set
		different reply routes for each branch.
		</para>
		<para>
		When called from a non-branc route, the reply route will be globally 
		set for tha current transaction - it will be called for all replies 
		belonging to that transaction. NOTE that only 
		<emphasis>one></emphasis> onreply_route can be armed for a transaction.
		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 (string)</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 {
	seturi("sip:bob@opensips.org");  # first branch
	append_branch("sip:alice@opensips.org"); # second branch

	t_on_reply("global"); # the "global" reply route 
	                      # is set the whole transaction
	t_on_branch("1");

	t_relay();
}

branch_route[1] {
	if ($rU=="alice")
		t_on_reply("alice"); # the "alice" reply route
		                      # is set only for second branch
}

onreply_route[alice] {
	xlog("received reply from alice\n");
}

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

	<section id="func_t_on_branch" xreflabel="t_on_branch()">
		<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 (string)</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_branch("1"); 
	t_relay();
} 

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

	<section id="func_t_inject_branches" xreflabel="t_inject_branches()">
		<title>
		<function moreinfo="none">t_inject_branches(source[,flags])</function>
		</title>
		<para>
		The function adds new SIP branches (destinations) to an existing 
		transaction and fires them (sends them out). The transaction may 
		already have ongoing branches (like in ringing state), which will not
		be affected by the injection of the new branches. Also it is possible 
		for the transaction not to have any ongoing branches at the moment of
		the injection (still, the transaction must wait for new branches, even
		if all existing ones are completed - see 
		the <xref linkend="func_t_wait_for_new_branches"/> function for this).
		</para>
		<para>
		The main usage scenario for this function (and also what makes it
		different from <xref linkend="func_t_relay"/> is the ability to add new
		branches to an ongoing transaction from script routes not related to 
		the transaction ( like timer route, event route, notification route,
		and other). In such routes, other functions/module used before the
		injection will point to the transaction to be affected by this
		injection - see the <emphasis>event_routing</emphasis> module.
		</para>
		<para>Parameters: </para>
		<itemizedlist>
			<listitem><para>
				<emphasis>source (string)</emphasis> - where to take the description
				for the new branches to be injected. It can be
				<itemizedlist>
					<listitem>
					<emphasis>event</emphasis> - the branch will be taken from
					the event attributes exposed in an event notification route
					(see <emphasis>event_routing</emphasis> module).
					</listitem>
					<listitem>
					<emphasis>msg</emphasis> - the branches will be taken from
					the RURI of the SIP message and from the additional
					branches (created by append_branch() function or similar).
					</listitem>
				</itemizedlist>
			</para></listitem>
			<listitem><para>
				<emphasis>flags (string, optional)</emphasis> - some additional flags 
				related to the injection process:
				<itemizedlist>
					<listitem>
					<emphasis>cancel</emphasis> or <emphasis>c</emphasis> 
					- cancel all the ongoing 
					existing branches from the transaction before injecting
					the new branches.
					</listitem>
					<listitem>
					<emphasis>l</emphasis> (last) - this is the last injected
					branch on this transaction, do not wait for any other
					branches to be injected.
					</listitem>

				</itemizedlist>
			</para></listitem>
		</itemizedlist>
		<example>
		<title><function>t_inject_branches</function> usage</title>
		<programlisting format="linespecific">
...
route[event_notification] {
	t_inject_branches("event");
}
...
</programlisting>
		</example>
	</section>

	<section id="func_t_wait_for_new_branches" xreflabel="t_wait_for_new_branches()">
		<title>
		<function moreinfo="none">t_wait_for_new_branches([branches])</function>
		</title>
		<para>
		This function instructs the existing SIP transaction to wait for new
		branches to be injected even after the completion of the existing 
		branches. This waiting will be done until the Final Response INVITE 
		timer (fr_inv_timeout) will hit for the transaction OR until the 
		maximum number of branches were injected (see parameter); of course,
		the waiting will be terminated if the transaction gets a 2xx final
		reply from one of the branches.
		</para>
		<para>
		Normally if you have a transaction with two branches and 
		they get, let's say, a 404 and 486 replies, the branches will be
		completed and transaction terminated by sending the 404 reply to the 
		caller. Still, if you do <emphasis>t_wait_for_new_branches</emphasis>
		before relaying the transaction, the transaction will not terminate
		upon the completion of the branches and not send the 404 to the caller
		- it will wait for new branches to be injected (see 
		<xref linkend="func_t_inject_branches"/> function) until the fr_inv timer
		hits.
		</para>
		<para>Parameters: </para>
		<itemizedlist>
			<listitem><para>
				<emphasis>branches (integer, options)</emphasis> - what is the
				maximum number of branches to be waited for.
			</para></listitem>
		</itemizedlist>
		<example>
		<title><function>t_wait_for_new_branches</function> usage</title>
		<programlisting format="linespecific">
...
t_newtran();
t_wait_for_new_branches();
t_relay();
...
</programlisting>
		</example>
	</section>

	<section id="func_t_wait_no_more_branches" xreflabel="t_wait_no_more_branches()">
		<title>
		<function moreinfo="none">t_wait_no_more_branches()</function>
		</title>
		<para>
		This function instructs the existing SIP transaction to stop wait
		for new any new branches to be injected. This functions should be 
		used for a transaction that is waiting for dynamic branches, via the
		<xref linkend="func_t_wait_for_new_branches"/> function.
		</para>
		<para>
		Usage scenario: your transaction is waiting for dynamic new branches
		(as a reusult of Push Notification). To a point, on an ongoing
		branch you receive a final reply - and the fact that the branch fails
		translates into stop waiting for any more branche (this is an example
		of a logic on deciding how long to wait for more branches, depending 
		on the answers you get from various devices, fix or mobile).
		</para>
		<example>
		<title><function>t_wait_no_more_branches</function> usage</title>
		<programlisting format="linespecific">
...
t_wait_no_more_branches();
...
</programlisting>
		</example>
	</section>

	<section id="func_t_add_hdrs" xreflabel="t_add_hdrs()">
		<title>
		<function moreinfo="none">t_add_hdrs("sip_hdrs")</function>
		</title>
		<para>
		Attach a set of headers to the existing transaction - these headers
		will be appended to all requests related to the transaction (outgoing
		branches, local ACKS, CANCELs).
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>sip_hdrs (string)</emphasis>
			</para></listitem>
		</itemizedlist>
		<example>
		<title><function>t_add_hdrs</function> usage</title>
		<programlisting format="linespecific">
...
t_add_hdrs("X-origin: 1.1.1.1\r\n");
...
</programlisting>
		</example>
	</section>

	<section id="func_t_add_cancel_reason" xreflabel="t_add_cancel_reason()">
		<title>
		<function moreinfo="none">t_add_cancel_reason("Reason_hdr")</function>
		</title>
		<para>
		This function is used to enforce from the script level a custom
		"Reason" header into a CANCEL request. Normally, the Reason header is
		inherited form the received CANCEL (note that CANCEL propagates in a
		hop-by-hop manner - it is re-generated at each hop), but this function
		can overwrite it. It must be called before relaying the CANCEL request
		and its input must be a fully formated Reason header with name, body 
		and CRLF.
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>reason_hdr (string)</emphasis>
			</para></listitem>
		</itemizedlist>
		<example>
		<title><function>t_add_cancel_reason</function> usage</title>
		<programlisting format="linespecific">
...
t_add_cancel_reason("Reason: SIP ;cause=200 ;text=\"Call completed elsewhere\"\r\n");
t_relay();
...
</programlisting>
		</example>
	</section>


	<section id="func_t_replicate" xreflabel="t_replicate()">
		<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>Parameters:</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>uri (string)</emphasis>
			</para></listitem>
			<listitem><para>
				<emphasis>flags (string, optional)</emphasis> - a set of flags for
				controlling the internal behaviour - for description see the above 
				<quote>t_relay([flags])</quote> function. Note that only
				<emphasis>no-dns-failover</emphasis> is
				applicable here.
			</para></listitem>
		</itemizedlist>
		<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 id="func_t_write_req" xreflabel="t_write_req()">
		<title>
		<function moreinfo="none">t_write_req(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>Parameters:</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>info (string)</emphasis>
			</para></listitem>
			<listitem><para>
				<emphasis>path (string)</emphasis>
			</para></listitem>
		</itemizedlist>
		<para>
		This functions can be used from REQUEST_ROUTE, FAILURE_ROUTE and 
		BRANCH_ROUTE.
		</para>
		<example>
		<title><function>t_write_req/unix</function> usage</title>
		<programlisting format="linespecific">
...
modparam("tm","tw_append","append1:Email=$avp(email);UA=$ua")
modparam("tm","tw_append","append2:body=$rb")
...
t_write_req("voicemail/append1","/tmp/appx_fifo");
...
t_write_unix("logger/append2","/var/run/logger.sock");
...
</programlisting>
		</example>
	</section>

	<section id="func_t_flush_flags" xreflabel="t_flush_flags()">
		<title>
		<function moreinfo="none">t_flush_flags()</function>
		</title>
		<para>
		Flush the flags from current request 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 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 id="func_t_anycast_replicate" xreflabel="t_anycast_replicate()">
		<title>
		<function moreinfo="none">t_anycast_replicate()</function>
		</title>
		<para>
		This function is used in an anycast setup to replicate a
		<emphasis>CANCEL</emphasis> or <emphasis>ACK</emphasis> method
		for whom there are no local transactions found. The function
		broadcasts the message to all the other nodes in the cluster,
		but only the <quote>owner</quote> of the transaction will be
		able to handle it.
		</para>
		<example>
		<title><function>t_anycast_replicate</function> usage</title>
		<programlisting format="linespecific">
...
if (is_method("ACK|CANCEL") &amp;&amp; !t_check_trans()) {
	t_anycast_replicate();
	exit;
}
...
</programlisting>
		</example>
	</section>

	<section id="func_t_reply_by_callid" xreflabel="t_reply_by_callid()">
		<title>
		<function moreinfo="none">t_reply_by_callid(code, reason_phrase, [callid], [cseq])</function>
		</title>
		<para>
		This function is used to send a reply to an existing INVITE
		transaction. The usual use case is when OpenSIPS is used as an UAS
		and when an INVITE is receveid, it is "parked" locally on
		OpenSIPS by replying to it with
		<quote>t_reply(180, "Ringing")</quote> or 
		<quote>t_reply(183, "Session Progress")</quote>
		and later we need to handle CANCEL or BYE for it and send
		'487 Request Terminated' to the original INVITE transaction.
		</para>
		<para>
		The callid and cseq used to identify the transaction
		will be obtained from the current messsage being processed.
		But they can be passed explicitly so that for example we can
		handle a BYE where the cseq must be the cseq
		of the INVITE minus one.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>t_reply_by_callid</function> usage</title>
		<programlisting format="linespecific">
...
route{
	if($rU == "LOCAL_PARK") {
		if(is_method("INVITE")) {
			$T_fr_timeout = 10;
			$T_fr_inv_timeout = 10;
			append_to_reply("Contact: sip:LOCAL_PARK@$socket_in(ip):$socket_in(port)\r\n");
			t_reply(180, "Ringing");
			t_wait_for_new_branches();
		} else if(is_method("CANCEL")) {
			if(!t_reply_by_callid(487, "Request Terminated")) {
				sl_send_reply(481, "Call Leg/Transaction Does Not Exist");
			} else {
				sl_send_reply(200, "OK");
			}
		} else if(is_method("BYE")) {
			$var(prev_cseq) = ($(cs{s.int}) - 1);
			if(!t_reply_by_callid(487, "Request Terminated", , $var(prev_cseq))) {
				sl_send_reply(481, "Call Leg/Transaction Does Not Exist");
			} else {
				sl_send_reply(200, "OK");
			}
		} else if(is_method("ACK")) {
			t_relay();
		}
		exit;
	}
}
...
</programlisting>
		</example>
	</section>

	</section>

	<section id="exported_pseudo_variables" xreflabel="Exported Pseudo-Variables">
		<title>Exported Pseudo-Variables</title>
		<para>
		Exported variables are listed in the next sections.
		</para>
		<section id="pv_T_branch_idx" xreflabel="$T_branch_idx">
		<title>$T_branch_idx</title>
			<para>
			<emphasis>$T_branch_idx</emphasis> - the index (starting with 0
			for the first branch) of the currently proccessed branch. This
			index makes sense only in BRANCH and REPLY routes (where the
			processing is per branch) and in FAILURE route (where it points
			to the branch with the last final reply on the transaction). In all
			the other types of routes, the value of this index will be NULL.
			</para>
		</section>
		<section id="pv_T_reply_code" xreflabel="$T_reply_code">
		<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 id="pv_T_fr_timeout" xreflabel="$T_fr_timeout">
		<title>$T_fr_timeout</title>
			<para>
			<emphasis>$T_fr_timeout (R/W)</emphasis> - the timeout
			for the final reply to the current transaction
			</para>
			<para>
			With each different
			request received, <emphasis>$T_fr_timeout</emphasis> will initially
			be equal to the
			<emphasis role='bold'><xref linkend="param_fr_timeout"/></emphasis> parameter.
			</para>
			<para>
			<emphasis>"$T_fr_timeout = NULL;"</emphasis> will reset it to
			<emphasis role='bold'><xref linkend="param_fr_timeout"/></emphasis>.
			</para>
		</section>
		<section id="pv_T_fr_inv_timeout" xreflabel="$T_fr_inv_timeout">
		<title>$T_fr_inv_timeout</title>
			<para>
			<emphasis>$T_fr_inv_timeout (R/W)</emphasis> - the timeout
			for the final reply to an INVITE request, after a 1XX reply
			was received.  This variable may also be set in an onreply_route
			(e.g. on 180 Ringing, after 100 Trying) and still take effect.
			</para>
			<para>
			With each different request received,
			<emphasis>$T_fr_inv_timeout</emphasis> will initially be equal to the
			<emphasis role='bold'>
			<xref linkend="param_fr_inv_timeout"/></emphasis> parameter.
			</para>
			<para>
			<emphasis>"$T_fr_inv_timeout = NULL;"</emphasis> will reset it to
			<emphasis role='bold'><xref linkend="param_fr_inv_timeout"/></emphasis>.
			</para>
		</section>
		<section id="pv_T_ruri" xreflabel="$T_ruri">
		<title>$T_ruri</title>
			<para>
			<emphasis>$T_ruri</emphasis> - the ruri of the current branch; this
			information is taken from the transaction structure, so you can
			access this information for any sip message (request/reply) that
			has a transaction.
			</para>
		</section>
		<section id="pv_bavp" xreflabel="$bavp">
		<title>$bavp(name)</title>
			<para>
			<emphasis>$bavp(name)</emphasis> - a particular type of avp that
			can have different values for each branch. They can only be used in
			BRANCH, REPLY and FAILURE routes. Otherwise NULL value is returned.
			</para>
		</section>
		<section id="pv_T_id" xreflabel="$T_id">
		<title>$T_id</title>
			<para>
			<emphasis>$T_id</emphasis> - returns the ID of the current 
			transaction. The ID is an opaque hexa string, unique for each
			transaction. If there is no current transaction,  NULL value is
			returned.
			</para>
		</section>
		<section id="pv_T_branch_last_reply_code" xreflabel="$T_branch_last_reply_code">
		<title>$T_branch_last_reply_code</title>
			<para>
				<emphasis>$T_branch_last_reply_code</emphasis> - returns the last reply
				code received for a branch specified as parameter. If no parameter is
				specified, the last reply for the current branch is retrieved.
			</para>
		</section>

	</section>


	<section id="exported_mi_functions" xreflabel="Exported MI Functions">
	<title>Exported MI Functions</title>

	<section id="mi_t_uac_dlg" xreflabel="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>headers</emphasis> - set of additional headers to
				be added to the request; at least 
				<quote>From</quote> and <quote>To</quote> headers must be
				specified)
			</para></listitem>
			<listitem><para>
				<emphasis>next_hop</emphasis> (optional) - next hop SIP URI (OBP).
			</para></listitem>
			<listitem><para>
				<emphasis>socket</emphasis> (optional) - local socket to be used for
				sending the request.
			</para></listitem>
			<listitem><para>
				<emphasis>body</emphasis> (optional) - request body (if present, requires the 
				<quote>Content-Type</quote> and <quote>Content-length</quote>
				headers)
			</para></listitem>
		</itemizedlist>
		<para>
		MI FIFO Command Format:
		</para>
		<programlisting  format="linespecific">
		opensips-cli -x mi t_uac_dlg method=INVITE ruri="sip:alice@127.0.0.1:7050" headers="From: sip:bobster@127.0.0.1:1337\r\nTo: sip:alice@127.0.0.1:7050\r\nContact: sip:bobster@127.0.0.1:1337\r\n"
		</programlisting>
	</section>

	<section id="mi_t_uac_cancel" xreflabel="t_uac_cancel">
		<title>
		<function moreinfo="none">t_uac_cancel</function>
		</title>
		<para>
		Generates and sends a CANCEL for an existing 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>
		<para>
		MI FIFO Command Format:
		</para>
		<programlisting  format="linespecific">
		opensips-cli -x mi t_uac_cancel "1-23454@127.0.0.1" "1 INVITE"
		</programlisting>
	</section>

	<section id="mi_t_hash" xreflabel="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>
		<para>
		MI FIFO Command Format:
		</para>
		<programlisting  format="linespecific">
		opensips-cli -x mi t_hash
		</programlisting>
	</section>

	<section id="mi_t_reply" xreflabel="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> (optional) - extra headers to be
				appended to the reply.
			</para></listitem>
			<listitem><para>
				<emphasis>body</emphasis> - (optional) reply body (if present, requires the
				<quote>Content-Type</quote> and <quote>Content-length</quote>
				headers)
			</para></listitem>
		</itemizedlist>
		<para>
		MI FIFO Command Format:
		</para>
		<programlisting  format="linespecific">
		opensips-cli -x mi t_reply 403 Forbidden 46961:1279687637 abcde .
		</programlisting>
	</section>

	</section>


	<section id="exported_statistics">
		<title>Exported Statistics</title>
		<para>
		Exported statistics are listed in the next sections. All statistics
		except <quote>inuse_transactions</quote> can be reset.
		</para>
		<section id="stat_received_replies" xreflabel="received_replies">
		<title>received_replies</title>
			<para>
			Total number of total replies received by TM module.
			</para>
		</section>
		<section id="stat_relayed_replies" xreflabel="relayed_replies">
		<title>relayed_replies</title>
			<para>
			Total number of replies received and relayed by TM module.
			</para>
		</section>
		<section id="stat_local_replies" xreflabel="local_replies">
		<title>local_replies</title>
			<para>
			Total number of replies local generated by TM module.
			</para>
		</section>
		<section id="stat_UAS_transactions" xreflabel="UAS_transactions">
		<title>UAS_transactions</title>
			<para>
			Total number of transactions created by received requests.
			</para>
		</section>
		<section id="stat_UAC_transactions" xreflabel="UAC_transactions">
		<title>UAC_transactions</title>
			<para>
			Total number of transactions created by local generated requests.
			</para>
		</section>
		<section id="stat_2xx_transactions" xreflabel="2xx_transactions">
		<title>2xx_transactions</title>
			<para>
			Total number of transactions completed with 2xx replies.
			</para>
		</section>
		<section id="stat_3xx_transactions" xreflabel="3xx_transactions">
		<title>3xx_transactions</title>
			<para>
			Total number of transactions completed with 3xx replies.
			</para>
		</section>
		<section id="stat_4xx_transactions" xreflabel="4xx_transactions">
		<title>4xx_transactions</title>
			<para>
			Total number of transactions completed with 4xx replies.
			</para>
		</section>
		<section id="stat_5xx_transactions" xreflabel="5xx_transactions">
		<title>5xx_transactions</title>
			<para>
			Total number of transactions completed with 5xx replies.
			</para>
		</section>
		<section id="stat_6xx_transactions" xreflabel="6xx_transactions">
		<title>6xx_transactions</title>
			<para>
			Total number of transactions completed with 6xx replies.
			</para>
		</section>
		<section id="stat_inuse_transactions" xreflabel="inuse_transactions">
		<title>inuse_transactions</title>
			<para>
			Number of transactions existing in memory at current time.
			</para>
		</section>
		<section id="stat_retransmission_req_T1_1" xreflabel="retransmission_req_T1_1">
		<title>retransmission_req_T1_1</title>
			<para>
			Number of request retransmissions due to T1 1 timer,
			the first retransmission interval (typical 500ms).
			</para>
		</section>
		<section id="stat_retransmission_req_T1_2" xreflabel="retransmission_req_T1_2">
		<title>retransmission_req_T1_2</title>
			<para>
			Number of request retransmissions due to T1 2 timer,
			the second retransmission interval (typical 1s).
			</para>
		</section>
		<section id="stat_retransmission_req_T1_3" xreflabel="retransmission_req_T1_3">
		<title>retransmission_req_T1_3</title>
			<para>
			Number of request retransmissions due to T1 3 timer,
			the third retransmission interval (typical 2s).
			</para>
		</section>
		<section id="stat_retransmission_req_T2" xreflabel="retransmission_req_T2">
		<title>retransmission_req_T2</title>
			<para>
			Number of request retransmissions due to T2 ,
			the final retransmission interval (typical 4s).
			</para>
		</section>
		<section id="stat_retransmission_rpl_T2" xreflabel="retransmission_rpl_T2">
		<title>retransmission_rpl_T2</title>
			<para>
			Number of reply retransmissions, all done with the same 
			retransmission interval T2, typical 4s.
			</para>
		</section>
		<section id="stat_timeout_finalresponse" xreflabel="timeout_finalresponse">
		<title>timeout_finalresponse</title>
			<para>
			Number of transactional timeouts without receiving any kind of reply (not
			even provisional) from the B side. Such timeouts indicate a 
			communication / reachability issue. Note: a single transaction may count
			multiple such timeouts due forking.
			</para>
		</section>
		<section id="stat_timeout_finalresponse_inc" xreflabel="timeout_finalresponse">
		<title>timeout_finalresponse</title>
			<para>
			Number of transactional INVITE timeouts without receiving a FINAL reply
			(provisional may be received) from the B side. Such timeouts indicate a 
			"not answer" event and it is not a signalling issue.
			Note: a single transaction may count multiple such timeouts due forking.
			</para>
		</section>
	</section>

</chapter>

