<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<section id="tm.functions" xmlns:xi="http://www.w3.org/2001/XInclude">
    <sectioninfo>
    </sectioninfo>

    <title>Functions</title>

    <section id="tm.f.t_relay">
	<title>
	    <function>t_relay([host, port])</function>
	</title>
	<para>
	    Relay a message statefully either to the destination indicated in the
		current URI (if called without any parameters) or to the specified 
		host and port. In the later case (host and port specified) the protocol
		used is the same protocol on which the message was received.
	</para>
	<para>
		<function>t_relay()</function> is the statefull version for 
		<function>forward()</function>
		while <function>t_relay(host, port)</function> is similar to 
		<function>forward(host, port)</function>.
	</para>
	<para>
		In the forward to uri case (<function>t_relay()</function>), if the
	    original URI was rewritten (by UsrLoc, RR, strip/prefix, etc.) the new
		URI will be taken). The destination (including the protocol) is 
		determined from the uri, using SIP specific DNS resolving if needed
		(NAPTR, SRV a.s.o depending also on the dns options).
	</para>
	<para>
		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>
	<example>
	    <title><function>t_relay</function> usage</title>
	    <programlisting>
...
if (!t_relay()) 
{ 
    sl_reply_error(); 
    break; 
};
...
	    </programlisting>
	</example>
    </section>

    <section id="tm.f.t_relay_to_udp">
	<title>
	    <function>t_relay_to_udp([ip, port])</function>
	</title>
	<para>
	    Relay a message statefully using a fixed protocol either to the 
		 specified fixed destination or to a destination derived from the 
		 message uri (if the host address and port are not specified).
		 These along with
	    <function>t_relay</function> are the functions most users want to
	    use--all other are mostly for programming. Programmers interested
	    in writing <acronym>TM</acronym> logic should review how t_relay is
	    implemented in tm.c and how <acronym>TM</acronym> callbacks work.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>ip</emphasis> - IP address where the message should be sent.
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>port</emphasis> - Port number.
		</para>
	    </listitem>
	</itemizedlist>
	<para>If no parameters are specified the message is sent to a destination
	 derived from the message uri (using sip sepcific DNS lookups), but with 
	 the protocol corresponding to the function name.</para>
	<example>
	    <title><function>t_relay_to_udp</function> usage</title>
	    <programlisting>
...
if (src_ip==10.0.0.0/8)
	t_relay_to_udp("1.2.3.4", "5060"); # sent to 1.2.3.4:5060 over udp
else
	t_relay_to_tcp(); # relay to msg. uri, but over tcp
...
	    </programlisting>
	</example>
    </section>

    <section id="tm.f.t_relay_to_tcp">
	<title>
	    <function>t_relay_to_tcp([ip, port])</function>
	</title>
	<para>
		See function <function>t_relay_to_udp([ip, port])</function>.
	</para>
    </section>

    <section id="tm.f.t_relay_to_tls">
	<title>
	    <function>t_relay_to_tls([ip, port])</function>
	</title>
	<para>
		See function <function>t_relay_to_udp([ip, port])</function>.
	</para>
    </section>

    <section id="tm.f.t_relay_to_sctp">
	<title>
	    <function>t_relay_to_sctp([ip, port])</function>
	</title>
	<para>
		See function <function>t_relay_to_udp([ip, port])</function>.
	</para>
    </section>

    <section id="tm.f.t_on_failure">
	<title>
	    <function>t_on_failure(failure_route)</function>
	</title>
	<para>
	    Sets failure 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
	    "202 I will take care of it"). Note that the set of
	    commands which are usable within failure_routes is strictly limited to
	    rewriting URI, initiating new branches, logging, and sending
	    stateful replies (<function>t_reply</function>). Any other commands
	    may result in unpredictable behavior and possible server
	    failure. Note that whenever failure_route is entered, uri is reset to
	    value which it had on relaying. If it temporarily changed during a
	    reply_route processing, subsequent reply_route will ignore the
	    changed value and use again the original one.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>failure_route</emphasis> - Failure route block to be called.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>t_on_failure</function> usage</title>
	    <programlisting>
...
route { 
    t_on_failure("1"); 
    t_relay(); 
} 

failure_route[1] {
    revert_uri(); 
    setuser("voicemail"); 
    append_branch(); 
}
...
	    </programlisting>
	</example>
	<para>
	    See <filename>test/onr.cfg</filename> for a more complex example of
	    combination of serial with parallel forking.
	</para>
    </section>
     <section id="tm.f.t_on_branch_failure">
	<title>
	    <function>t_on_branch_failure(branch_failure_route)</function>
	</title>
	<para>
	    Sets the branch_failure routing block, to which control is passed on each
	    negative response to a transaction. This route is run before deciding if
	    the transaction is complete. In the referred block, you can start a new
	    branch which is required for failover of multiple outbound flows (RFC 5626).
	    Note that the set of commands which are usable within a branch_failure route
	    is limited to a subset of the failure_rotue commands including logging,
	    rewriting URI and initiating new branches. Any other commands may generate
	    errors or result in unpredictable behavior.
	    Note that whenever failure_route is entered, uri is reset to
	    value which it had on relaying. If it temporarily changed during a
	    reply_route processing, subsequent reply_route will ignore the
	    changed value and use again the original one.
	</para>
	<para>Function Parameters:</para>
	<itemizedlist>
	    <listitem>
			<para><emphasis>branch_failure_route</emphasis> - Name of the branch_failure route
			block to be called (it is prefixed internally with 'tm:branch-failure:').
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>t_on_branch_failure</function> usage</title>
	    <programlisting>
...
route {
    t_on_branch_failure("myroute");
    t_relay();
}

event_route[tm:branch-failure:myroute] {
    if (t_check_status("430|403") {
        unregister("location", "$tu", "$T_reply_ruid");
    }
}
...
	    </programlisting>
	</example>
    </section>
 
	 <section id="tm.f.t_on_reply">
	<title>
	    <function>t_on_reply(onreply_route)</function>
	</title>
	<para>
	    Sets the reply routing block, to which control is passed when a
	    reply for the current transaction is received.
	    Note that the set of commands which are usable within onreply_routes is
	     limited.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>onreply_route</emphasis> - Onreply route block to be
			called.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>t_on_reply</function> usage</title>
	    <programlisting>
...
loadmodule "/usr/local/lib/ser/modules/nathelper.so"
...
route { 
	/* if natted */
	t_on_reply("1"); 
	t_relay(); 
} 

onreply_route[1] {
	if (status=~ "(183)|2[0-9][0-9]"){
		force_rtp_proxy();
		search_append('^(Contact|m)[ \t]*:.*sip:[^>[:cntrl:]]*', ';nat=yes');
	}
	if (nat_uac_test("1")){
		fix_nated_contact();
	}
}
	    </programlisting>
	</example>
	</section>

	<section id="tm.f.t_on_branch">
	<title>
	    <function>t_on_branch(branch_route)</function>
	</title>
	<para>
	    Sets the branch routing block, to which control is passed after
	    forking (when a new branch is created). For now branch routes
	    are intended only for last minute changes of the SIP messages
	    (like adding new headers).
	    Note that the set of commands which are usable within branch_routes is
	    very limited. It is not possible to generate a reply.
	</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>
	<example>
	    <title><function>t_on_branch</function> usage</title>
	    <programlisting>
...
route { 
	t_on_branch("1"); 
	t_relay(); 
} 

branch_route[1] {
	if (uri=~"sip:[0-9]+"){
		append_hf("P-Warn: numeric uri\r\n");
	}
}
	    </programlisting>
	</example>
	</section>

    <section id="tm.f.t_newtran">
	<title>
	    <function>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>
	<example>
	    <title><function>t_newtran</function> usage</title>
	    <programlisting>
...
if (t_newtran()) { 
    log("UAS logic"); 
    t_reply("999","hello"); 
} else sl_reply_error();
...
	    </programlisting>
	</example>
	<para>
	    See test/uas.cfg for more examples.
	</para>
    </section>

    <section id="tm.f.t_reply">
	<title>
	    <function>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>
	<example>
	    <title><function>t_reply</function> usage</title>
	    <programlisting>
...
t_reply("404", "Not found");
...
	    </programlisting>
	</example>
    </section>

    <section id="tm.f.t_lookup_request">
	<title>
	    <function>t_lookup_request()</function>
	</title>
	<para>
	    Checks if a transaction exists. Returns a positive value if so,
	    negative otherwise.  Most likely you will not want to use it, as a
	    typical application of a look-up is to introduce a new transaction
	    if none was found. However this is safely (atomically) done using
	    <function>t_newtran</function>.
	</para>
	<example>
	    <title><function>t_lookup_request</function> usage</title>
	    <programlisting>
...
if (t_lookup_request()) {
    ...
};
...
	    </programlisting>
	</example>
    </section>

    <section id="tm.f.t_retransmit_reply">
	<title>
	    <function>t_retransmit_reply()</function>
	</title>
	<para>
	    Retransmits a reply sent previously by UAS transaction.
	</para>
	<example>
	    <title><function>t_retransmit_reply</function> usage</title>
	    <programlisting>
...
t_retransmit_reply();
...
	    </programlisting>
	</example>
    </section>

    <section id="tm.f.t_release">
	<title>
	    <function>t_release()</function>
	</title>
	<para>
	    Remove transaction from memory (it will be first put on a wait
	    timer to absorb delayed messages).
	</para>
	<example>
	    <title><function>t_release</function> usage</title>
	    <programlisting>
...
t_release();
...
	    </programlisting>
	</example>
    </section>

    <section id="tm.f.t_forward_nonack">
	<title>
	    <function>t_forward_nonack([ip, port])</function>
	</title>
	<para>
		Mainly for internal usage -- forward a non-ACK request statefully.
		Variants of this functions can enforce a specific transport protocol.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>ip</emphasis> - IP address where the message should be sent.
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>port</emphasis> - Port number.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>t_forward_nonack</function> usage</title>
	    <programlisting>
...
t_forward_nonack("1.2.3.4", "5060");
...
	    </programlisting>
	</example>
    </section>

   <section id="tm.f.t_forward_nonack_udp">
	<title>
	    <function>t_forward_nonack_udp(ip, port)</function>
	</title>
	<para>
	    See function <function>t_forward_nonack([ip, port])</function>.
	</para>
    </section>

   <section id="tm.f.t_forward_nonack_tcp">
	<title>
	    <function>t_forward_nonack_tcp(ip, port)</function>
	</title>
	<para>
	    See function <function>t_forward_nonack([ip, port])</function>.
	</para>
    </section>

   <section id="tm.f.t_forward_nonack_tls">
	<title>
	    <function>t_forward_nonack_tls(ip, port)</function>
	</title>
	<para>
	    See function <function>t_forward_nonack([ip, port])</function>.
	</para>
    </section>

   <section id="tm.f.t_forward_nonack_sctp">
	<title>
	    <function>t_forward_nonack_sctp(ip, port)</function>
	</title>
	<para>
	    See function <function>t_forward_nonack([ip, port])</function>.
	</para>
    </section>

	<section id="tm.f.t_set_fr">
	<title>
	    <function>t_set_fr(fr_inv_timeout [, fr_timeout])</function>
	</title>
	<para>
		Sets the fr_inv_timeout and optionally fr_timeout for the current
		transaction or for transactions created during the same script 
		invocation, after calling this function.
		If the transaction is already created (e.g called after
		 <function>t_relay()</function> or in an onreply_route) all the
		 branches will have their final response timeout updated on-the-fly.
		If one of the parameters is 0, its value won't be changed.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>fr_inv_timeout</emphasis> - new final response timeout
			(in milliseconds) for INVITEs. See also 
			<varname>fr_inv_timer</varname>.
		</para>
		<para><emphasis>fr_timeout</emphasis> - new final response timeout
		 	(in milliseconds) for non-INVITE transaction, or INVITEs which 
			haven't received yet a provisional response. See also
			<varname>fr_timer</varname>.
		</para>
	    </listitem>
	</itemizedlist>
	<para>
		See also: 
			<varname>fr_timer</varname>,
			<varname>fr_inv_timer</varname>,
			<function>t_reset_fr()</function>.
	</para>
	<example>
	    <title><function>t_set_fr</function> usage</title>
	    <programlisting>
...
route { 
	t_set_fr(10000); # set only fr invite timeout to 10s
	t_on_branch("1");
	t_relay(); 
} 

branch_route[1] {
	# if we are calling the pstn, extend the invite timeout to 50s
	# for all the branches, and set the no-reply-received timeout to 2s
	if (uri=~"sip:[0-9]+"){
		t_set_fr(50000, 2000); 
	}
}
	    </programlisting>
	</example>
	</section>

	<section id="tm.f.t_reset_fr">
	<title>
	    <function>t_reset_fr()</function>
	</title>
	<para>
		Resets the <varname>fr_inv_timer</varname> and 
		<varname>fr_timer</varname> for the current transaction to the default
		values (set using the tm module parameters
		<varname>fr_inv_timer</varname> and <varname>fr_timer</varname>).
	</para>
	<para>
		It will effectively cancel any previous calls to 
		<function>t_set_fr</function> for the same transaction.
	</para>
	<para>
		See also: <varname>fr_timer</varname>,
				<varname>fr_inv_timer</varname>,
				<function>t_set_fr</function>.
	</para>
	<example>
		<title><function>t_reset_fr</function> usage</title>
		<programlisting>
...
route { 
...
		t_reset_fr();
...
} 
		</programlisting>
	</example>
	</section>


	<section id="tm.f.t_set_max_lifetime">
	<title>
	    <function>t_set_max_lifetime(inv_lifetime, noninv_lifetime)</function>
	</title>
	<para>
		Sets the maximum lifetime for the current INVITE or non-INVITE 
		transaction, or for transactions created during the same script
		invocation, after calling this function (that's why it takes values
		for both INVITE and non-INVITE).
		If one of the parameters is 0, its value won't be changed.
	</para>
	<para>
		It works as a per transaction <varname>max_inv_lifetime</varname> or
		<varname>max_noninv_lifetime</varname>.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>inv_lifetime</emphasis> - maximum INVITE transaction
			lifetime (in milliseconds). See also 
			<varname>max_inv_lifetime</varname>.
		</para>
		<para><emphasis>noninv_lifetime</emphasis> - maximum non-INVITE 
			transaction lifetime (in milliseconds).
			See also <varname>max_noninv_lifetime</varname>.
		</para>
	    </listitem>
	</itemizedlist>
	<para>
		See also: <varname>max_inv_lifetime</varname>,
				<varname>max_noninv_lifetime</varname>,
				<function>t_reset_max_lifetime</function>.
	</para>
	<example>
		<title><function>t_set_max_lifetime</function> usage</title>
		<programlisting>
...
route { 
    if (src_ip=1.2.3.4)
        t_set_max_lifetime(120000, 0); # set only max_inv_lifetime to 120s
    else
        t_set_max_lifetime(90000, 15000); # set the maximum lifetime to 90s if
                                          # the current transaction is an 
                                          # INVITE and to 15s if not
} 

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

	<section id="tm.f.t_reset_max_lifetime">
	<title>
	    <function>t_reset_max_lifetime()</function>
	</title>
	<para>
		Resets the the maximum lifetime for the current INVITE or non-INVITE 
		transaction to the default value (set using the tm module parameter
		<varname>max_inv_lifetime</varname> or 
		<varname>max_noninv_lifetime</varname>).
	</para>
	<para>
		It will effectively cancel any previous calls to 
		<function>t_set_max_lifetime</function> for the same transaction.
	</para>
	<para>
		See also: <varname>max_inv_lifetime</varname>,
				<varname>max_noninv_lifetime</varname>,
				<function>t_set_max_lifetime</function>.
	</para>
	<example>
		<title><function>t_reset_max_lifetime</function> usage</title>
		<programlisting>
...
route { 
...
		t_reset_max_lifetime();
...
} 
		</programlisting>
	</example>
	</section>

	<section id="tm.f.t_set_retr">
	<title>
	    <function>t_set_retr(retr_t1_interval, retr_t2_interval)</function>
	</title>
	<para>
		Sets the retr_t1_interval and retr_t2_interval for the current
		transaction or for transactions created during the same script 
		invocation, after calling this function.
		If one of the parameters is 0, it's value won't be changed.
		If the transaction is already created (e.g called after
		 <function>t_relay()</function> or in an onreply_route) all the
		 existing branches will have their retransmissions intervals updated 
		 on-the-fly:
		 if the retransmission interval for the branch has not yet reached T2
		  the interval will be reset to retr_t1_interval, else to 
		  retr_t2_interval. Note that the change will happen after the current
		  interval expires (after the next retransmission, the next-next 
		  retransmission will take place at retr_t1_interval or 
		  retr_t2_interval).
		 All new branches of the same transaction will start with the new 
		 values.
		 This function will work even if it's called in the script before
		a transaction creating function (e.g.: t_set_retr(500, 4000);
		t_relay()). All new transaction created after this function call, 
		during the same script invocation will use the new values.
		Note that this function will work only if tm is compile with
		 -DTM_DIFF_RT_TIMEOUT (which increases every transaction size with
		 4 bytes).
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>retr_t1_interval</emphasis> - new T1 retransmission
			interval (in milliseconds). See also
			<varname>retr_t1_timeout</varname>.
		</para>
		<para><emphasis>retr_t2_interval</emphasis> - new T2 (or maximum) 
			retransmission interval (in milliseconds). See also
			<varname>retr_t2_timeout</varname>.
		</para>
	    </listitem>
	</itemizedlist>
	<para>
		See also: 
			<varname>retr_timer1</varname>,
			<varname>retr_timer2</varname>,
			<function>t_reset_retr()</function>.
	</para>
	<example>
	    <title><function>t_set_retr</function> usage</title>
	    <programlisting>
...
route { 
	t_set_retr(250, 0); # set only T1 to 250 ms
	t_on_branch("1");
	t_relay(); 
} 

branch_route[1] {
	# if we are calling the a remote pstn, extend T1 and decrease T2
	# for all the branches
	if (uri=~"sip:[0-9]+"){
		t_set_retr(500, 2000); 
	}
}
	    </programlisting>
	</example>
	</section>


	<section id="tm.f.t_reset_retr">
	<title>
	    <function>t_reset_retr()</function>
	</title>
	<para>
		Resets the <varname>retr_timer1</varname> and 
		<varname>retr_timer2</varname> for the current transaction to the 
		default values (set using the tm module parameters
		<varname>retr_timer1</varname> and <varname>retr_timer2</varname>).
	</para>
	<para>
		It will effectively cancel any previous calls to 
		<function>t_set_retr</function> for the same transaction.
	</para>
	<para>
		See also: <varname>retr_timer1</varname>,
				<varname>retr_timer2</varname>,
				<function>t_set_retr</function>.
	</para>
	<example>
		<title><function>t_reset_retr</function> usage</title>
		<programlisting>
...
route { 
...
		t_reset_retr();
...
} 
		</programlisting>
	</example>
	</section>

	<section id="tm.f.t_set_auto_inv_100">
	<title>
	    <function>t_set_auto_inv_100(0|1)</function>
	</title>
	<para>
		Switch automatically sending 100 replies to INVITEs on/off on a 
		per transaction basis. It overrides the 
		<varname>auto_inv_100</varname> value for the current transaction.
	</para>
	<para>
		See also: <varname>auto_inv_100</varname>.
	</para>
	<example>
		<title><function>t_set_auto_inv_100</function> usage</title>
		<programlisting>
...
route { 
...
	if (src_ip==1.2.3.0/24)
		t_set_auto_inv_100(0); # turn off automatic 100 replies
...
} 
		</programlisting>
	</example>
	</section>

	<section id="tm.f.t_branch_timeout">
	<title>
	    <function>t_branch_timeout()</function>
	</title>
	<para>
		Returns true if the failure route is executed for a branch that did
		timeout. It can be used from 
		<emphasis>failure_route</emphasis> and
		<emphasis>branch-failure</emphasis> event route.
	</para>
	<example>
	    <title><function>t_branch_timeout</function> usage</title>
	    <programlisting>
...
failure_route[0]{ 
	if (t_branch_timeout()){
		log("timeout\n");
		# ... 
	}
} 
	    </programlisting>
	</example>
	</section>

<section id="tm.f.t_branch_replied">
	<title>
	    <function>t_branch_replied()</function>
	</title>
	<para>
		Returns true if the failure route is executed for a branch that did
		receive at least one reply in the past (the "current" reply is not 
		taken into account). It can be used from
		<emphasis>failure_route</emphasis>  and
		<emphasis>branch-failure</emphasis> event route.
	</para>
	<example>
	    <title><function>t_branch_replied</function> usage</title>
	    <programlisting>
...
failure_route[0]{ 
	if (t_branch_timeout()){
		if (t_branch_replied())
			log("timeout after receiving a reply (no answer?)\n");
		else
			log("timeout, remote side seems to be down\n");
		# ... 
	}
} 
	    </programlisting>
	</example>
	</section>

<section id="tm.f.t_any_timeout">
	<title>
	    <function>t_any_timeout()</function>
	</title>
	<para>
		Returns true if at least one of the current transactions branches
		did timeout.
	</para>
	<example>
	    <title><function>t_any_timeout</function> usage</title>
	    <programlisting>
...
failure_route[0]{ 
	if (!t_branch_timeout()){
		if (t_any_timeout()){
			log("one branch did timeout\n");
			sl_send_reply("408", "Timeout");
		}
	}
} 
	    </programlisting>
	</example>
	</section>

<section id="tm.f.t_any_replied">
	<title>
	    <function>t_any_replied()</function>
	</title>
	<para>
		Returns true if at least one of the current transactions branches
		did receive some reply in the past. If called from a failure or
		onreply route, the "current" reply is not taken into account.
	</para>
	<example>
	    <title><function>t_any_replied</function> usage</title>
	    <programlisting>
...
onreply_route[0]{ 
	if (!t_any_replied()){
		log("first reply received\n");
		# ...
	}
} 
	    </programlisting>
	</example>
</section>

<section id="tm.f.t_grep_status">
	<title>
	    <function>t_grep_status("code")</function>
	</title>
	<para>
		Returns true if "code" is the final reply received (or locally
		 generated) in at least one of the current transactions branches.
	</para>
	<example>
	    <title><function>t_grep_status</function> usage</title>
	    <programlisting>
...
onreply_route[0]{ 
	if (t_grep_status("486")){
		/* force a 486 reply, even if this is not the winning branch */
		t_reply("486", "Busy");
	}
} 
	    </programlisting>
	</example>
</section>

<section id="tm.f.t_is_canceled">
	<title>
	    <function>t_is_canceled()</function>
	</title>
	<para>
		Returns true if the current transaction was canceled.
	</para>
	<example>
	    <title><function>t_is_canceled</function> usage</title>
	    <programlisting>
...
failure_route[0]{ 
	if (t_is_canceled()){
		log("transaction canceled\n");
		# ...
	}
} 
	    </programlisting>
	</example>
	</section>

	<section id="tm.f.t_is_expired">
	<title>
	    <function>t_is_expired()</function>
	</title>
	<para>
		Returns true if the current transaction has already been expired,
		i.e. the max_inv_lifetime/max_noninv_lifetime interval has already
		elapsed.
	</para>
	<example>
	    <title><function>t_is_expired</function> usage</title>
	    <programlisting>
...
failure_route[0]{ 
	if (t_is_expired()){
		log("transaction expired\n");
		# There is no point in adding a new branch.
	}
} 
	    </programlisting>
	</example>
	</section>

    <section id="tm.f.t_relay_cancel">
	<title>
	    <function>t_relay_cancel()</function>
	</title>
	<para>
		Forwards the CANCEL if the corresponding INVITE transaction
		exists. The function is supposed to be used at the very
		beginning of the script, because the CANCELs can be caught
		and the rest of the script can be bypassed this way. Do not disable
		<varname>reparse_invite</varname> module parameter, and call
		<varname>t_relay_cancel()</varname> right after the sanity tests.
	</para>
	<para>
		Return value is 0 (drop) if the corresponding INVITE was found
		and the CANCELs were successfully sent to the pending branches,
		true if the INVITE was not found, and false in case of any error.
	</para>
	<example>
	    <title><function>t_relay_cancel</function> usage</title>
	    <programlisting>

if (method == CANCEL) {
	if (!t_relay_cancel()) {  # implicit drop if relaying was successful,
                                  # nothing to do

		# corresponding INVITE transaction found but error occurred
		sl_reply("500", "Internal Server Error");
		drop;
	}
	# bad luck, corresponding INVITE transaction is missing,
	# do the same as for INVITEs
}
	    </programlisting>
	</example>
    </section>

    <section id="tm.f.t_lookup_cancel">
	<title>
	    <function>t_lookup_cancel([1])</function>
	</title>
	<para>
		Returns true if the corresponding INVITE transaction exists
		for a CANCEL request. The function can be called at the beginning
		of the script to check whether or not the CANCEL can be immediately
		forwarded bypassing the rest of the script. Note however that
		<function>t_relay_cancel</function> includes
		<function>t_lookup_cancel</function> as well, therefore it is not
		needed to explicitly call this function unless something has to be
		logged for example.
	</para>
	<para>
		If the function parameter (optional) is set to 1, the message flags
		are overwritten with the flags of the INVITE. isflagset() can be used
		to check the flags of the previously forwarded INVITE in this case.
	</para>
	<example>
	    <title><function>t_lookup_cancel</function> usage</title>
	    <programlisting>

if (method == CANCEL) {
	if (t_lookup_cancel()) {
		log("INVITE transaction exists");
		if (!t_relay_cancel()) {  # implicit drop if
                                          # relaying was successful,
                                          # nothing to do

			# corresponding INVITE transaction found
			# but error occurred
			sl_reply("500", "Internal Server Error");
			drop;
		}
	}
	# bad luck, corresponding INVITE transaction is missing,
	# do the same as for INVITEs
}
	    </programlisting>
	</example>
    </section>

    <section id="tm.f.t_drop_replies">
	<title>
	    <function>t_drop_replies([mode])</function>
	</title>
	<para>
		Drops all the previously received replies in failure_route
		block to make sure that none of them is picked up again.
	</para>
	<para>
		The parameter 'mode' controls which replies are dropped: 'a'
		or missing - all replies are dropped; 'l' - replies received for
		last set of branches are dropped; 'n' - no reply is dropped.
	</para>
	<para>
		Dropping replies works only if a new branch is added to the
		transaction, or it is explicitly replied in the script!
	</para>
	<example>
	    <title><function>t_drop_replies()</function> usage</title>
	    <programlisting>
...
failure_route[0]{ 
	if (t_check_status("5[0-9][0-9]")){
		# I do not like the 5xx responses,
		# so I give another chance to "foobar.com",
		# and I drop all the replies to make sure that
		# they are not forwarded to the caller.
		t_drop_replies();
		
		rewritehostport("foobar.com");
		append_branch();
		t_relay();
	}
} 
	    </programlisting>
	</example>
    </section>

    <section id="tm.f.t_save_lumps">
	<title>
	    <function>t_save_lumps()</function>
	</title>
	<para>
		Forces the modifications of the processed SIP message
		to be saved in shared memory before t_relay() is called.
		The new branches which are created in failure_route will
		contain the same modifications, and any other modification
		after t_save_lumps() will be lost.
	</para>
	<para>
		Note that t_relay() automatically saves the modifications
		when it is called the first time, there is no need for
		t_save_lumps() unless message changes between t_save_lumps()
		and t_relay() must not be propagated to failure_route.
	</para>
	<para>
		The transaction must be created by t_newtran() before
		calling t_save_lumps().
	</para>
	<example>
	    <title><function>t_save_lumps()</function> usage</title>
	    <programlisting>
route {
	...
	t_newtran();
	append_hf("hf1: my first header\r\n");
	...
	t_save_lumps();
	append_hf("hf2: my second header\r\n");
	...
	t_on_failure("1");
	t_relay();
}

failure_route[1] {
	append_branch();
	append_hf("hf3: my third header\r\n");
	#
	# This branch contains hf1 and hf3, but does
	# not contain hf2 header.
	# hf2 would be also present here without
	# t_save_lumps().
	...
	t_relay();
}
	    </programlisting>
	</example>
    </section>

	<section id="tm.f.t_load_contacts">
		<title>
		<function moreinfo="none">t_load_contacts()</function>
		</title>
		<para>
		  This is the first of the three functions that can be used
		  to implement 
		  serial/parallel forking based on q and +sip.instance
		  values of individual branches in the destination set.
		</para>
		<para>
		  Function <function>t_load_contacts()</function> removes
		  all branches from the current destination set and stores
		  them into the XAVP whose name is configured with the
		  parameter <varname>contacts_avp</varname>.
		  Note that you have to
		  configure this parameter before you can use the function, the
		  parameter is set to NULL by default, which disables
		  the function.
		</para>
		<para>
		  If the destination set contains only one branch,
		  the function does nothing.
		</para>
		<para>
		  If the current destination set contains more than one branch,
		  the function sorts them
		  according to increasing value of the q parameter and
		  then stores the branches in reverse order into the XAVP.
		</para>
		<para>
		  The q parameter of a branch contains a value from range 0-1.0
		  and it  expresses relative preferrence of the branch
		  among all branches in the destination set.
		  The higher the q value the more preference the
		  user agent gave to the branch. Branches with higher q
		  values will be tried before branches with lower ones
		  when serial forking takes place.
		</para>
		<para>
		  After calling <function>t_load_contacts()</function>, function
		  <function>t_next_contacts()</function> and possibly
		  also <function>t_next_contact_flow()</function> need
		  to be called
		  one or more times in order to retrieve the branches based
		  on their q value.
		</para>
		<para>
		  Function returns 1 if loading of contacts succeeded or
		  there was nothing to do. In case of an error,
		  function returns -1 (see syslog).
		</para>
		<para>
		This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
		</para>
		<example>
		<title><function>t_load_contacts</function> usage</title>
		<programlisting format="linespecific">
...
if (!t_load_contacts()) {
        sl_send_reply("500", "Server Internal Error - Cannot load contacts");
        exit;
};
...
</programlisting>
		</example>
	</section>

	<section id="tm.f.t_next_contacts">
		<title>
		<function moreinfo="none">t_next_contacts()</function>
		</title>
		<para>
		  Function <function>t_next_contacts()</function> is the
		  second of the three functions that can be used to
		  implement serial/parallel
		  forking based on the q value of the individual branches
		  in a destination set.
		</para>
		<para>
		  The function adds to request a new destination set that
		  includes the highest priority contacts in contacts_avp,
		  but only one contact with the same +sip.instance value is
		  included.  Duplicate contacts are added to contact_flows_avp
		  for later consumption by function 
		  <function>next_contact_flow()</function>.
		  Upon each call, Request URI is rewritten with
		  the first contact and the remaining contacts (if any) are
		  added as branches. Then all highest priority contacts
		  are removed from contacts_avp.
		</para>
		<para>
		  Function does nothing if <varname>contact_avp</varname> has
		  no values.
		</para>
		<para>
		Function returns 1 if contacts_avp was not empty and a
		destination set was successfully added,
		returns -2 if contacts_avp was empty and thus there was
		nothing to do, and returns -1 in case of an error (see
		syslog).
          	Function can be called from REQUEST_ROUTE and FAILURE_ROUTE.
		</para>
		<para>
		  Note that if you use <function>t_load_contacts</function>
		  and <function>t_next_contacts</function> functions then
		  you should also set the value of
		  <varname>restart_fr_on_each_reply</varname>
		  parameter to 0. If you do not do that, it can
		  happen that a
		  broken user agent that retransmits 180 periodically will keep
		  resetting the fr_inv_timer value and serial
		  forking never happens.
		</para>
		<para>
		Before calling t_relay(), you can check if the
		previous call of <function>next_contacts()</function>
		consumed all branches
		by checking if <varname>contact_avp</varname> and
		<varname>contact_flows_avp</varname> are not anymore set.
		Based on
		that test, you can then use t_set_fr() function to set
		timers according to your needs.
		</para>
		<example>
		<title><function>t_next_contacts</function> usage</title>
		<programlisting format="linespecific">
...
# First call after t_load_contacts() when transaction does not exist yet
# and contacts should be available
if (!t_next_contacts()) {
        sl_send_reply("500", "Server Internal Error - Cannot get contacts");
} else {
        t_relay();
};
...
# Following call, when transaction exists and there may or may not be
# contacts left
if (!t_next_contacts()) {
        t_reply("408", "Request Timeout");
} else {
        t_relay();
};
...
</programlisting>
		</example>
	</section>

	<section id="tm.f.t_next_contact_flow">
		<title>
		<function moreinfo="none">t_next_contact_flow()</function>
		</title>
		<para>
		  Function <function>t_next_contact_flow()</function>
		  is the last of the three functions that can be used to
		  implement serial/parallel forking based on the q value
		  and instance value of individual branches in a destination set.
		</para>
		<para>
		  Function adds a new branch to the request that includes
		  the first contact from <varname>contact_flows_avp</varname>
		  that matches the +sip.instance value of the flow that has failed.
		  Upon each call, Request URI is rewritten with the contact. The
		  used contact is removed from <varname>contact_flows_avp</varname>.
		</para>
		<para>
		  Function does nothing if there are
		  no <varname>contact_flows_avp</varname> values.
		</para>
		<para>
		Function returns 1 if <varname>contact_flows_avp</varname>
		was not empty and a destination set was successfully added,
		returns -2 if <varname>contacts_avp</varname>
		was empty and thus there was
		nothing to do, and returns -1 in case of an error (see
		syslog).
		This function can be used from a BRANCH_FAILURE event route.
		</para>
		<example>
		<title><function>t_next_contact_flow</function> usage</title>
		<programlisting format="linespecific">
...
event_route[tm:branch-failure:outbound]
{
	if (t_next_contact_flow())
	{
		t_relay();
	} else {
		xlog("L_INFO", "No more flows\n");
	}
...
</programlisting>
		</example>
	</section>

	<section id="tm.f.t_check_status">
		<title>
		<function moreinfo="none">t_check_status(re)</function>
		</title>
		<para>
		Returns true if the regular 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 ANY_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="tm.f.t_check_trans">
	<title>
		<function>t_check_trans()</function>
	</title>
	<para>
		<function>t_check_trans()</function> can be used to quickly check if
		a message belongs or is related to a transaction. It behaves
		differently for different types of messages:
		<itemizedlist>
			<listitem>
				<para>For a SIP Reply it returns true if the reply belongs to
				an existing transaction and false otherwise.</para>
			</listitem>
			<listitem>
				<para>For a CANCEL it behaves exactly as
				<function>t_lookup_cancel()</function>: returns true if a
				corresponding INVITE transaction exists for the CANCEL and
				false otherwise.</para>
			</listitem>
			<listitem>
				<para>For ACKs to negative replies or for ACKs to local
				transactions it will terminate the script if the ACK belongs
				to a transaction (it would make very little sense to process
				an ACK to a negative reply  for an existing transaction in
				some other way then to simply pass it to tm) or return false
				if not.</para>
			</listitem>
			<listitem>
				<para>For end-to-end ACKs (ACKs to 2xx responses for forwarded
				INVITE transactions) it will return true if the corresponding
				INVITE transaction is found and still active and false if not.
				</para>
				<note>
				<para>
				Note that the e2e ACK matching is more of a hint
				then a certainty. A delayed e2e ACK might arrive after the
				transaction wait time elapses, when the INVITE transaction no
				longer exists and thus would not match anything. There are
				also cases when tm would not keep all the information needed
				for e2e ACK matching (since this is not needed for a statefull
				proxy and it requires additional memory, tm will not keep this
				information unless needed by some other module or callbacks).
				</para>
				</note>
			</listitem>
			<listitem>
				<para>For other requests (non ACKs and non CANCELs), in case of
				a retransmission matching a transaction, it resends the last
				reply for that transaction and terminates the config execution.
				Otherwise, it returns false (in case of new requests for which
				no transaction exists yet).</para>
			</listitem>
		</itemizedlist>
	</para>
	<note><para>
		An important difference from kamailio version is that for an ACK to
		negative reply or for a local transaction, the script execution will be
		immediately stopped and the message handled by tm, instead of returning
		true.
	</para></note>
	<para><function>t_check_trans()</function> functionality for requests,
		except for the e2e ACK matching, can be replicated in the script
		using <function>t_lookup_cancel()</function> and
		<function>t_lookup_request()</function>.
	</para>
	<para>See also: <function>t_lookup_request()</function>,
					<function>t_lookup_cancel()</function>.
	</para>
	<example>
		<title><function>t_check_trans</function> usage</title>
		<programlisting>

if ( method == "CANCEL" &amp;&amp; !t_check_trans())
	sl_reply("403", "cancel out of the blue forbidden");
# note: in this example t_check_trans() can be replaced by t_lookup_cancel()

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

	<section id="tm.f.t_set_disable_6xx">
	<title>
		<function>t_set_disable_6xx(0|1)</function>
	</title>
	<para>
		Turn off/on 6xx replies special rfc conformant handling on a per
		transaction basis. If turned off
		(<function>t_set_disable_6xx("1")</function>) 6XXs will be treated
		like normal replies.
	</para>
	<para>
		It overrides the <varname>disable_6xx_block</varname> value for
		the current transaction.
	</para>
	<para>
		See also: <varname>disable_6xx_block</varname>.
	</para>
	<example>
		<title><function>t_set_disable_6xx</function> usage</title>
		<programlisting>
...
route {
...
	if (src_ip==1.2.3.4) # bad user agent that sends 603
		t_set_disable_6xx(1); # turn off 6xx special handling
...
}
		</programlisting>
	</example>
	</section>

	<section id="tm.f.t_set_disable_failover">
	<title>
		<function>t_set_disable_failover(0|1)</function>
	</title>
	<para>
		Turn off/on dns failover on a per transaction basis.
	</para>
	<para>
		See also: <varname>use_dns_failover</varname>.
	</para>
	<example>
		<title><function>t_set_disable_failover</function> usage</title>
		<programlisting>
...
route {
...
	if (uri=~"@foo.bar$")
		t_set_disable_failover(1); # turn off dns failover
...
}
		</programlisting>
	</example>
	</section>

	<section id="tm.f.t_set_disable_internal_reply">
	<title>
		<function>t_set_disable_internal_reply(0|1)</function>
	</title>
	<para>
		Turn off/on sending internally a SIP reply in case of relay errors.
	</para>
	<example>
		<title><function>t_set_disable_internal_reply</function> usage</title>
		<programlisting>
...
t_set_disable_internal_reply(1); # turn off sending internal reply on error
if(!t_relay()) {
   send_reply("500", "Server error");
}
...
		</programlisting>
	</example>
	</section>

	<section id="tm.f.t_replicate">
	<title>
	    <function>t_replicate([params])</function>
	</title>
	<para>
		Replicate the SIP request to a specific address.
	</para>
	<para>
		There are several function prototypes:
		<itemizedlist>
		<listitem><para>
	    <function>t_replicate([uri])</function>,
		</para></listitem>
		<listitem><para>
	    <function>t_replicate(host, port)</function>,
		</para></listitem>
		<listitem><para>
	    <function>t_replicate_udp(host, port)</function>
		</para></listitem>
		<listitem><para>
	    <function>t_replicate_tcp(host, port)</function>
		</para></listitem>
		<listitem><para>
	    <function>t_replicate_tls(host, port)</function>
		</para></listitem>
		<listitem><para>
	    <function>t_replicate_sctp(host, port)</function>
		</para></listitem>
		<listitem><para>
	    <function>t_replicate_to(proto, hostport)</function>
		</para></listitem>
		</itemizedlist>
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>uri</emphasis> - SIP URI where the message should be sent.
			It can be given via a script variable. It is optional - when missing, the
			dst-uri or r-uri are used as next hop address.
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>host</emphasis> - host address where the message should be sent.
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>port</emphasis> - port number.
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>proto</emphasis> - transport protocol to be used.
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>hostport</emphasis> - address in "host:port" format. It can be
		given via an AVP.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>t_replicate</function> usage</title>
	    <programlisting>
...
# sent to 1.2.3.4:5060 over tcp
t_replicate("sip:1.2.3.4:5060;transport=tcp");

# sent to 1.2.3.4:5061 over tls
$var(h) = "1.2.3.4:5061";
t_replicate("sip:$var(h);transport=tls");

# sent to 1.2.3.4:5060 over udp
t_replicate_to_udp("1.2.3.4", "5060");
...
	    </programlisting>
	</example>
    </section>
	<section id="tm.f.t_relay_to">
	<title>
	    <function>t_relay_to(proxy, flags)</function>
	</title>
	<para>
		Forward the SIP request to a specific address, controlling internal
		behavior via flags.
	</para>
	<para>
		There are several function prototypes:
		<itemizedlist>
		<listitem><para>
	    <function>t_relay_to()</function>,
		</para></listitem>
		<listitem><para>
	    <function>t_relay_to(proxy)</function>,
		</para></listitem>
		<listitem><para>
	    <function>t_relay_to(flags)</function>
		</para></listitem>
		<listitem><para>
	    <function>t_relay_to(proxy, flags)</function>
		</para></listitem>
		</itemizedlist>
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>proxy</emphasis> - address where the request should
		be sent. Format is: "proto:host:port" - any of proto or port can be
		ommitted, along with the semicolon after or before.
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>flags</emphasis> - bitmask integer value to control
		the internal behavior. Bits can be:
		</para>
		<itemizedlist>
	    <listitem>
		<para><emphasis>0x01</emphasis> - do not generate 100 reply.
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>0x02</emphasis> - do not generate reply on internal
		error.
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>0x04</emphasis> - disable dns failover.
		</para>
	    </listitem>
		</itemizedlist>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>t_relay_to</function> usage</title>
	    <programlisting>
...
# sent to 1.2.3.4:5060 over tcp
t_relay_to("tcp:1.2.3.4:5060");

# sent to 1.2.3.4 over tls
t_relay_to("tls:1.2.3.4");

# sent to dst URI or R-URI without a 100 reply
t_relay_to("0x01");
...
	    </programlisting>
	</example>
    </section>


	<section id="tm.f.t_set_no_e2e_cancel_reason">
	<title>
		<function>t_set_no_e2e_cancel_reason(0|1)</function>
	</title>
	<para>
		Enables/disables reason header (RFC 3326) copying from the triggering
		received CANCEL to the generated hop-by-hop CANCEL. 0 enables and
		1 disables.
	</para>
	<para>
		It overrides the <varname>e2e_cancel_reason</varname> setting (module
		 parameter) for the current transaction.
	</para>
	<para>
		See also: <varname>e2e_cancel_reason</varname>.
	</para>
	<example>
		<title><function>t_set_no_e2e_cancel_reason</function> usage</title>
		<programlisting>
...
route {
...
	if (src_ip!=10.0.0.0/8) #  don't trust CANCELs from the outside
		t_set_no_e2e_cancel_reason(1); # turn off CANCEL reason header copying
...
}
		</programlisting>
	</example>
	</section>

	<section id="tm.f.t_is_set">
	<title>
	    <function>t_is_set(target)</function>
	</title>
	<para>
		Return true if the attribute specified by 'target' is set for transaction.
	</para>
	<para>The target parameter can be:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>branch_route</emphasis> - the function returns true if a
			branch route is set to be executed.
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>failure_route</emphasis> - the function returns true if a
			failure route is set to be executed.
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>onreply_route</emphasis> - the function returns true if an
			onreply route is set to be executed.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>t_replicate</function> usage</title>
	    <programlisting>
...
if(!t_is_set("failure_route"))
    LM_DBG("no failure route will be executed for current transaction\n");
...
	    </programlisting>
	</example>
    </section>

	<section id="tm.f.t_use_uac_headers">
	<title>
	    <function>t_use_uac_headers()</function>
	</title>
	<para>
	Set internal flags to tell tm to use UAC side for building headers for
	local generated requests (ACK, CANCEL) - useful when changing From/To
	headers using other functions than uac_replace_[from|to]().
	</para>
	<para>It returns true.</para>
	<example>
	    <title><function>t_use_uac_headers</function> usage</title>
	    <programlisting>
...
t_use_uac_headers();
...
	    </programlisting>
	</example>
    </section>

</section>