<?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>
	<revhistory>
	    <revision>
		<revnumber>$Revision: 1.6.2.1 $</revnumber>
		<date>$Date: 2008/06/20 17:37:22 $</date>
	    </revision>
	</revhistory>
    </sectioninfo>

    <title>Functions</title>

    <section id="t_relay_to_udp">
	<title>
	    <function>t_relay_to_udp(ip, port)</function>,
	    <function>t_relay_to_tcp(ip, port)</function>
	</title>
	<para>
	    Relay a message statefully to a fixed destination. This along with
	    <function>t_relay</function> is the function 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>
	<example>
	    <title><function>t_relay_to_udp</function> usage</title>
	    <programlisting>
...
t_relay_to_udp("1.2.3.4", "5060");
...
	    </programlisting>
	</example>
    </section>

    <section id="t_relay">
	<title>
	    <function>t_relay()</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>
	<example>
	    <title><function>t_relay</function> usage</title>
	    <programlisting>
...
if (!t_relay()) 
{ 
    sl_reply_error(); 
    break; 
};
...
	    </programlisting>
	</example>
    </section>
    
    <section id="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="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="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 drop a message or 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="append_branch">
	<title>
	    <function>append_branch()</function>
	</title>
	<para>
	    Similarly to <function>t_fork_to</function>, it extends destination
	    set by a new entry. The difference is that current URI is taken
	    as new entry.
	</para>
	<example>
	    <title><function>append_branch</function> usage</title>
	    <programlisting>
...
set_user("john"); 
t_fork(); 
set_user("alice");
t_fork(); 
t_relay();
...
	    </programlisting>
	</example>
    </section>

    <section id="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="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="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 looku-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="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="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="t_forward_nonack">
	<title>
	    <function>t_forward_nonack(ip, port)</function>
	</title>
	<para>
	    mainly for internal usage--forward a non-ACK request statefully.
	</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="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. 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>.
	</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="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 only from the 
		<emphasis>failure_route</emphasis>.
	</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="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 only from the 
		<emphasis>failure_route</emphasis>.
	</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="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="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="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>
