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

<chapter>
    <chapterinfo>
	<revhistory>
	    <revision>
		<revnumber>$Revision: 1.3.2.1 $</revnumber>
		<date>$Date: 2005/06/22 23:12:08 $</date>
	    </revision>
	</revhistory>
    </chapterinfo>
    <title>User's Guide</title>
    
    <section>
	<title>Overview</title>
	<para>
	    <acronym>TM</acronym> module enables stateful processing of &sip; transactions. The main
	    use of stateful logic, which is costly in terms of memory and <acronym>CPU</acronym>, is
	    some services inherently need state. For example, transaction-based accounting (module
	    acc) needs to process transaction state as opposed to individual messages, and any kinds
	    of forking must be implemented statefully. Other use of stateful processing is it trading
	    <acronym>CPU</acronym> caused by retransmission processing for memory. That makes
	    however only sense if <acronym>CPU</acronym> consumption per request is huge. For
	    example, if you want to avoid costly <acronym>DNS</acronym> resolution for every
	    retransmission of a request to an unresolvable destination, use stateful mode. Then,
	    only the initial message burdens server by <acronym>DNS</acronym> queries, subsequent
	    retransmissions will be dropped and will not result in more processes blocked by
	    <acronym>DNS</acronym> resolution. The price is more memory consumption and higher
	    processing latency.
	</para>
	<para>
	    From user's perspective, there are these major functions : t_relay, t_relay_to_udp
		and t_relay_to_tcp. All of them
	    setup transaction state, absorb retransmissions from upstream, generate downstream
	    retransmissions and correlate replies to requests. t_relay forwards to current &uri; (be
	    it original request's &uri; or a &uri; changed by some of &uri;-modifying functions,
	    such as sethost). t_relay_to_udp and t_relay_to_tcp forward to a specific address
		over UDP or TCP respectively.
	</para>
	<para>
	    In general, if <acronym>TM</acronym> is used, it copies clones of received &sip;
	    messages in shared memory. That costs the memory and also <acronym>CPU</acronym> time
	    (memcpys, lookups, shmem locks, etc.)  Note that non-<acronym>TM</acronym> functions
	    operate over the received message in private memory, that means that any core operations
	    will have no effect on statefully processed messages after creating the transactional
	    state. For example, calling record_route <emphasis>after</emphasis> t_relay is pretty
	    useless, as the <acronym>RR</acronym> is added to privately held message whereas its
	    <acronym>TM</acronym> clone is being forwarded.
	</para>
	<para>
	    <acronym>TM</acronym> is quite big and uneasy to program--lot of mutexes, shared memory
	    access, malloc & free, timers--you really need to be careful when you do anything. To
	    simplify <acronym>TM</acronym> programming, there is the instrument of callbacks. The
	    callback mechanisms allow programmers to register their functions to specific event. See
	    t_hooks.h for a list of possible events.
	</para>
	<para>
	    Other things programmers may want to know is &uac;--it is a very simplistic code which
	    allows you to generate your own transactions. Particularly useful for things like
	    NOTIFYs or <acronym>IM</acronym> gateways. The &uac; takes care of all the transaction
	    machinery: retransmissions , FR timeouts, forking, etc.  See t_uac prototype in uac.h
	    for more details. Who wants to see the transaction result may register for a callback.
	</para>
    </section>
    <section>
	<title>Dependencies</title>
	<section>
	    <title>&ser; Modules</title>
	    <para>
		The following modules must be loaded before this module:
	    	<itemizedlist>
		    <listitem>
			<para>
			    <emphasis>No dependencies on other &ser; modules</emphasis>.
			</para>
		    </listitem>
	    	</itemizedlist>
	    </para>
	</section>
	<section>
	    <title>External Libraries or Applications</title>
	    <para>
		The following libraries or applications must be installed before running
		&ser; with this module loaded:
	    	<itemizedlist>
		    <listitem>
			<para>
			    <emphasis>None</emphasis>.
			</para>
		    </listitem>
	    	</itemizedlist>
	    </para>
	</section>
    </section>
    <section>
	<title>Exported Parameters</title>
	<section>
	    <title><varname>fr_timer</varname> (integer)</title>
	    <para>
		Timer which hits if no final reply for a request or ACK for a negative INVITE reply
		arrives (in seconds).
	    </para>
	    <para>
		<emphasis>
		    Default value is 30 seconds.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>fr_timer</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "fr_timer", 10)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>fr_inv_timer</varname> (integer)</title>
	    <para>
		Timer which hits if no final reply for an INVITE arrives after a provisional message
		was received (in seconds).
	    </para>
	    <para>
		<emphasis>
		    Default value is 120 seconds.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>fr_inv_timer</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "fr_inv_timer", 200)
...
</programlisting>
	    </example>
	</section>

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

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

	<section>
	    <title><varname>retr_timer1p1</varname> (integer)</title>
	    <para>
		Retransmission period.
	    </para>
	    <para>
		<emphasis>
		    Default value is 1 second.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>retr_timer1p1</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "retr_timer1p1", 2)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>retr_timer1p2</varname> (integer)</title>
	    <para>
		Retransmission period.
	    </para>
	    <para>
		<emphasis>
		    Default value is 2 * <varname>retr_timer1p1</varname> second.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>retr_timer1p2</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "retr_timer1p2", 4)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>retr_timer1p3</varname> (integer)</title>
	    <para>
		Retransmission period.
	    </para>
	    <para>
		<emphasis>
		    Default value is 4 * <varname>retr_timer1p1</varname> second.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>retr_timer1p4</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "retr_timer1p3", 8)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>retr_timer2</varname> (integer)</title>
	    <para>
		Maximum retransmission period.
	    </para>
	    <para>
		<emphasis>
		    Default value is 4 seconds.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>retr_timer2</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "retr_timer2", 8)
...
</programlisting>
	    </example>
	</section>

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

	<section>
	    <title><varname>ruri_matching</varname> (integer)</title>
	    <para>
		The parameter controls whether the Request-URI should be
		included in pre-RFC3261 transaction maching. When set 1 then
		the Request-URI will be included, when set to 0 then it will be
		not included.
	    </para>
	    <para>
		<emphasis>
		    Default value is 1 (include Request-URI).
		</emphasis>
	    </para>
	</section>

	<section>
	    <title><varname>via1_matching</varname> (integer)</title>
	    <para>
		The parameter controls whether the topmost Via header field
		should be included in pre-RFC3261 transaction maching. When set
		1 then the topmost Via header field will be included, when set
		to 0 then it will be not included.
	    </para>
	    <para>
		<emphasis>
		    Default value is 1 (include topmost Via header field).
		</emphasis>
	    </para>
	</section>

	<section>
	    <title><varname>uac_from</varname> (string)</title>
	    <para>
		This parameter allows to configure the URI that will be put in
		the From header field of SIP request generated localy by the
		UAC in tm module. This parameter is currently not used.
	    </para>
	    <para>
		<emphasis>
		    Default value is "sip:foo@foo.bar".
		</emphasis>
	    </para>
	</section>

	<section>
	    <title><varname>unix_tx_timeout</varname> (integer)</title>
	    <para>
		Maximum timeout in seconds for the request sent over the unix
		domain socket interface (using t_write_unix function). The
		function will indicate failure if it does not manage to send
		all the data within the interval configured by this parameter.
	    </para>
	    <para>
		<emphasis>
		    Default value is 2 seconds.
		</emphasis>
	    </para>
	</section>

	<section>
	    <title><varname>restart_fr_on_each_reply</varname> (integer)</title>
	    <para>
		The parameter controls whether the FR timer will be restarted on
		each provisional reply received.
	    </para>
	    <para>
		<emphasis>
		    Default value is 1 (yes).
		</emphasis>
	    </para>
	</section>

	<section>
	    <title><varname>fr_timer_avp</varname> (string)</title>
	    <para>
		This parameter makes it possible to override the value of FR
		(final reply) timer on per-transaction basis. TM module can
		pick the value of the timer from an AVP. The name or ID of the
		AVP can be configured by this parameter. If there is no such
		AVP then the default value configured through fr_timer
		parameter will be used.
	    </para>
	    <para>
		<emphasis>
		    Default value is "callee_fr_timer".
		</emphasis>
	    </para>
	</section>

	<section>
	    <title><varname>fr_inv_timer_avp</varname> (string)</title>
	    <para>
		This parameter makes it possible to override the value of FR
		Invite (final response for INVITE transactions) timer on
		per-transaction basis. TM module can pick the value of the
		timer from an AVP. The name or ID of the AVP can be configured
		by this parameter. If there is no such AVP then the default
		value configured through fr_inv_timer parameter will be used.
	    </para>
	    <para>
		<emphasis>
		    Default value is "callee_fr_inv_timer".
		</emphasis>
	    </para>
	</section>

	<section>
	    <title><varname>tw_append</varname> (string)</title>
	    <para>
		This parameter configures additional information that can be
		passed over the FIFO or unix domain socket interfaces by TM
		module to another application. TM module can pass values of
		AVPs, SIP message header fields, or the message body. Syntax of
		the parameter is as follows:
	    </para>
	    <programlisting>
tw_append = name ':' element ( ';' element ) *
element   = [ title '=' ] ( avp_val | hdr_val )
element   = title '=' body_val
avp_val   = "avp" '[' avp_spec ']'
hdr_val   = "hdr" '[' hdr_name ']'
body_val  = "msg[body]"
</programlisting>
	    <para>
		<emphasis>
		    Default value is "".
		</emphasis>
	    </para>

	    <example>
		<title>Set <varname>tw_append</varname> parameter</title>
		<para>
		    Pass the value of callee_fr_timer AVP, the contents of
		    Subject header field, and the whole SIP message body to the
		    application over FIFO or unix domain socket interface.
		</para>
		<programlisting format="linespecific">
...
modparam("tm", "tw_append", "params:avp[callee_fr_timer];hdr[Subject];body=msg[body]")
...
</programlisting>
	    </example>
	</section>


    </section>
    <section>
	<title>Exported Functions</title>
	<section>
	    <title>
		<function moreinfo="none">t_relay_to_udp(ip, port)</function>,
		<function moreinfo="none">t_relay_to_tcp(ip, port)</function>,
		<function moreinfo="none">t_relay_to_tls(ip, port)</function>
	    </title>
	    <para>
		Relay a message statefully to a fixed destination. This along with <function
		    moreinfo="none">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 format="linespecific">
...
t_relay_to_udp("1.2.3.4", "5060");
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title>
		<function moreinfo="none">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 format="linespecific">
...
if (!t_relay()) { sl_reply_error(); break; };
...
</programlisting>
	    </example>
	</section>




	<section>
	    <title>
		<function moreinfo="none">t_on_failure(reply_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>). Note that the set of command which are usable within reply_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
		reply_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>reply_route</emphasis> - Reply route block to be called.
		    </para>
		</listitem>
	    </itemizedlist>
	    <example>
		<title><function>t_on_failure</function> usage</title>
		<programlisting format="linespecific">
...
route { 
    t_on_failure("1"); 
    t_relay(); 
} 

failure_route[1] {
    revert_uri(); 
    setuser("voicemail"); 
    append_branch(); 
}
...
</programlisting>
	    </example>
	    <para>
		See test/onr.cfg for a more complex example of combination
		of serial with parallel forking.
	    </para>
	</section>

	<section>
	    <title>
		<function moreinfo="none">t_on_failure(reply_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>). Note that the set of command which are usable within reply_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
		reply_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>reply_route</emphasis> - Reply route block to be called.
		    </para>
		</listitem>
	    </itemizedlist>
	    <example>
		<title><function>t_on_failure</function> usage</title>
		<programlisting format="linespecific">
...
route { 
    t_on_failure("1"); 
    t_relay(); 
} 

failure_route[1] {
    revert_uri(); 
    setuser("voicemail"); 
    append_branch(); 
}
...
</programlisting>
	    </example>
	    <para>
		See test/onr.cfg for a more complex example of combination
		of serial with parallel forking.
	    </para>
	</section>

	<section>
	    <title>
		<function moreinfo="none">t_on_failure(reply_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>). Note that the set of command which are usable within reply_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
		reply_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>reply_route</emphasis> - Reply route block to be called.
		    </para>
		</listitem>
	    </itemizedlist>
	    <example>
		<title><function>t_on_failure</function> usage</title>
		<programlisting format="linespecific">
...
route { 
    t_on_failure("1"); 
    t_relay(); 
} 

failure_route[1] {
    revert_uri(); 
    setuser("voicemail"); 
    append_branch(); 
}
...
</programlisting>
	    </example>
	    <para>
		See test/onr.cfg for a more complex example of combination
		of serial with parallel forking.
	    </para>
	</section>

	<section>
	    <title>
		<function moreinfo="none">t_on_reply(onreply_route)</function>
	    </title>
	    <para>
		Sets reply routing block, to which control is passed when a
		reply is received from one of downstream branches. Only a
		limited set of functions is available in onreply_route
		blocks. The routing block will be called for every reply
		received from downstream. A typical use for onreply_route
		blocks would be rewriting contacts with private IP addresses in
		200 OK replies by nathelper module.
	    </para>
	    <para>Meaning of the parameters is as follows:</para>
	    <itemizedlist>
		<listitem>
		    <para><emphasis>onreply_route</emphasis> - Reply route block to be called.
		    </para>
		</listitem>
	    </itemizedlist>
	    <example>
		<title><function>t_on_reply</function> usage</title>
		<programlisting format="linespecific">
...
route { 
    t_on_reply("1"); 
    t_relay(); 
} 

onreply_route[1] {
    fix_nated_contact();
    force_rtp_proxy();
}
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title>
		<function moreinfo="none">t_check_status(regex)</function>
	    </title>
	    <para>
		This function can be used to check the status code in replies
		from failure_route and onreply_route blocks. It allows to
		differentiate processing based on the status code received.
	    </para>
	    <para>Meaning of the parameters is as follows:</para>
	    <itemizedlist>
		<listitem>
		    <para><emphasis>regex</emphasis> - Regular expression to be
		    matched agains the status code.
		    </para>
		</listitem>
	    </itemizedlist>
	    <example>
		<title><function>t_check_status</function> usage</title>
		<programlisting format="linespecific">
...
failure_route[1] {
    if (t_check_status("486")) {
        # Busy
        t_relay_to_udp("1.2.3.4", "5060");
    };
 }
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title>
		<function moreinfo="none">t_write_req(fifo, application)</function>
	    </title>
	    <para>
		Send the request ove the FIFO interface to another application,
		such as SEMS.
	    </para>
	    <para>Meaning of the parameters is as follows:</para>
	    <itemizedlist>
		<listitem>
		    <para><emphasis>fifo</emphasis> - Name of the FIFO interface.
		    </para>
		</listitem>
		<listitem>
		    <para><emphasis>application</emphasis> - Name of the application.
		    </para>
		</listitem>
	    </itemizedlist>
	</section>

	<section>
	    <title>
		<function moreinfo="none">t_write_unix(socket, application)</function>
	    </title>
	    <para>
		Send the request ove the unix domain socket interface to another application,
		such as SEMS.
	    </para>
	    <para>Meaning of the parameters is as follows:</para>
	    <itemizedlist>
		<listitem>
		    <para><emphasis>socket</emphasis> - Filename of the unix
		    domain socket.
		    </para>
		</listitem>
		<listitem>
		    <para><emphasis>application</emphasis> - Name of the application.
		    </para>
		</listitem>
	    </itemizedlist>
	</section>

	<section>
	    <title>
		<function moreinfo="none">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 format="linespecific">
...
set_user("john"); 
t_fork(); 
set_user("alice");
t_fork(); 
t_relay();
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title>
		<function moreinfo="none">t_newtran()</function>
	    </title>
	    <para>
		Creates a new transaction, returns a negative value on error. This is the only way a
		script can add a new transaction in an atomic way. Typically, it is used to deploy a
		&uas;.
	    </para>
	    <example>
		<title><function>t_newtran</function> usage</title>
		<programlisting format="linespecific">
...
if (t_newtran()) { 
    log("UAS logic"); 
    t_reply("999","hello"); 
} else sl_reply_error();
...
</programlisting>
	    </example>
	    <para>
		See test/uas.cfg for more examples.
	    </para>
	</section>

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

	<section>
	    <title>
		<function moreinfo="none">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 format="linespecific">
...
if (t_lookup_request()) {
    ...
};
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title>
		<function moreinfo="none">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 format="linespecific">
...
t_retransmit_reply();
...
</programlisting>
	    </example>
	</section>

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

	<section>
	    <title>
		<function moreinfo="none">t_replicate(ip, port)</function>,
		<function moreinfo="none">t_replicate_udp(ip, port)</function>,
		<function moreinfo="none">t_replicate_tcp(ip, port)</function>,
		<function moreinfo="none">t_replicate_tls(ip, port)</function>
	    </title>
	    <para>
		Replicate a message to another server. Functions with "_tls"
		suffix are only available with additional TLS package.
	    </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>
	</section>

	<section>
	    <title>
		<function moreinfo="none">t_forward_nonack(ip,
		port)</function>,
		<function moreinfo="none">t_forward_nonack_uri()</function>,
		<function moreinfo="none">t_forward_nonack_udp(ip,
		port)</function>,
		<function moreinfo="none">t_forward_nonack_tcp(ip,
		port)</function>,
		<function moreinfo="none">t_forward_nonack_tls(ip, port)</function>
	    </title>
	    <para>
		mainly for internal usage--forward a non-ACK request
		statefully. t_forward_nonack_tls is only available with
		additional TLS package.
	    </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 format="linespecific">
...
t_forward_nonack("1.2.3.4", "5060");
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title>External Usage of <acronym>TM</acronym></title>

	    <para>
		There are applications which would like to generate &sip; transactions without too
		big involvement in &sip; stack, transaction management, etc. An example of such an
		application is sending instant messages from a website. To address needs of such
		apps, &ser; accepts requests for new transactions via fifo pipes too. If you want to
		enable this feature, start <acronym>FIFO</acronym> server with configuration option.
	    </para>
	    <para>
		fifo=<quote>/tmp/ser_fifo</quote>
	    </para>
	    <para>
		Then, an application can easily launch a new transaction by writing a transaction
		request to this named pipe. The request must follow very simple format, which is
	    </para>
	    <programlisting format="linespecific">
 :t_uac_from:[&lt;file_name&gt;]\n
 &lt;method&gt;\n
 &lt;sender's uri&gt;\n
 &lt;dst uri&gt;\n
 &lt;CR_separated_headers&gt;\n
 &lt;body&gt;\n
 .\n
 \n
</programlisting>
	    <para>
		(Filename is to where a report will be dumped. ser assumes /tmp
		as file's directory.)
	    </para>
	    <para>
		Note the the request write must be atomic, otherwise it might get intermixed with
		writes from other writers. You can easily use it via Unix command-line tools, see
		the following example:
	    </para>
	    <screen format="linespecific">
[jiri@bat jiri]$ cat &gt; /tmp/ser_fifo
:t_uac_from:xxx
MESSAGE
sip:sender@iptel.org
sip:mrx@iptel.org
header:value
foo:bar
bznk:hjhjk
p_header: p_value

body body body
yet body
end of body
.

</screen>
	    <para>
		or cat test/transaction.fifo &gt; /tmp/ser_fifo
	    </para>
	</section>
	<section>
	    <title>Known Issues</title>
	    <itemizedlist>
		<listitem>
		    <para>
			We don't have authentication merging on forking.
		    </para>
		</listitem>
		<listitem>
		    <para>
			Local ACK/CANCELs copy'n'pastes Route and ignores deleted
			Routes.
		    </para>
		</listitem>
		<listitem>
		    <para>
			6xx should be delayed.
		    </para>
		</listitem>
		<listitem>
		    <para>
			Possibly, performance could be improved by not parsing non-INVITEs, as they
			do not be replied with 100, and do not result in ACK/CANCELs, and other
			things which take parsing. However, we need to rethink whether we don't need
			parsed headers later for something else. Remember, when we now conserver a
			request in sh_mem, we can't apply any pkg_mem operations to it any
			more. (that might be redesigned too).
		    </para>
		</listitem>
		<listitem>
		    <para>
			Another performance improvement may be achieved by not parsing
			CSeq in replies until reply branch matches branch of an INVITE/CANCEL
			in transaction table.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<function>t_replicate</function> should be done more cleanly--Vias, Routes,
			etc. should be removed from a message prior to replicating it (well, does
			not matter any longer so much as there is a new replication module).
		    </para>
		</listitem>
		<listitem>
		    <para>
			<acronym>SNMP</acronym> support (as nobody cares about
			<acronym>SNMP</acronym>, in particular for <acronym>TM</acronym>, I will drop this item soon).
		    </para>
		</listitem>
	    </itemizedlist>
	</section>
    </section>
</chapter>

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