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

<chapter>
    <chapterinfo>
	<revhistory>
	    <revision>
		<revnumber>$Revision: 1.1 $</revnumber>
		<date>$Date: 2003/07/23 20:53:27 $</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 statefuly. 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 unresolveable destination, use stateful mode. Then,
	    only the initial message burdens server by <acronym>DNS</acronym> queries, subsequent
	    retranmissions 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 two major functions : t_relay and t_relay_to. Both
	    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 forwards to a specific address.
	</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 statefuly 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 programm--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 simplictic 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 behviour 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 cancelled if possible,
		silently dropped otherwise. Preferably, it is turned off to allow very long ringing.
		This behaviour 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>
    <section>
	<title>Exported Functions</title>
	<section>
	    <title>
		<function moreinfo="none">t_relay_to(ip, port)</function>
	    </title>
	    <para>
		Relay a message statefuly 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</function> usage</title>
		<programlisting format="linespecific">
...
t_relay_to("1.2.3.4", "5060");
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title>
		<function moreinfo="none">t_relay()</function>
	    </title>
	    <para>
		Relay a message statefuly 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_negative(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 refered 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 useable 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 behaviour 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_negative</function> usage</title>
		<programlisting format="linespecific">
...
route { 
    t_on_negative("1"); 
    t_relay(); 
} 

reply_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">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 typicall 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_forward_nonack(ip, port)</function>
	    </title>
	    <para>
		mainly for internal usage--forward a non-ACK request statefuly.
	    </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:
-->
