- improved documentation system

- documentation makefiles
- proper documentation dependency tracking in makefiles
- XML-based dialect of docbook used with xi:include inclusions

modules/tm/doc/Makefile

@@ -0,0 +1,29 @@
+#
+# The list of documents to build (without extensions)
+#
+DOCUMENTS = tm
+
+#
+# The root directory containing Makefile.doc
+#
+ROOT_DIR=../../..
+
+#
+# Validate docbook documents before generating output
+# (may be slow)
+#
+#VALIDATE=1
+
+#
+# You can override the stylesheet used to generate
+# xhtml documents here
+#
+#XHTML_XSL=$(ROOT_DIR)/doc/stylesheets/xhtml.xsl
+
+#
+# You can override the stylesheet used to generate
+# plain text documents here
+#
+#TXT_XSL=$(XHTML_XSL)
+
+include $(ROOT_DIR)/Makefile.doc

modules/tm/doc/api.xml

@@ -0,0 +1,160 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
+                      "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd">
+
+<section id="tm.api" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <sectioninfo>
+	<revhistory>
+	    <revision>
+		<revnumber>$Revision$</revnumber>
+		<date>$Date$</date>
+	    </revision>
+	</revhistory>
+    </sectioninfo>
+
+    <title>TM Module API</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="/tmp/ser_fifo"
+    </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>
+ :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>
+[jiri@bat jiri]$ cat &gt; /tmp/ser_fifo
+:t_uac_from:xxx
+MESSAGE
+sip:[email protected]
+sip:[email protected]
+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 id="defines">
+	<title>Defines</title>
+	<itemizedlist>
+	    <listitem>
+		<para>
+		    ACK_TAG enables stricter matching of acknowledgments
+		    including to-tags. Without it, to-tags are ignored. It is
+		    disabled by default for two reasons:
+		</para>
+		<itemizedlist>
+		    <listitem>
+			<para>
+			    It eliminates an unlikely race condition in which
+			    transaction's to-tag is being rewritten by a 200 OK
+			    whereas an ACK is being looked up by to-tag.
+			</para>
+		    </listitem>
+		</itemizedlist>
+		<itemizedlist>
+		    <listitem>
+			<para>
+			    It makes UACs happy who set wrong to-tags.
+			</para>
+		    </listitem>
+		</itemizedlist>
+		<para>
+		    It should not make a difference, as there may be only one
+		    negative reply sent upstream and 200/ACKs are not matched
+		    as they constitute another transaction. It will make no
+		    difference at all when the new magic cookie matching is
+		    enabled anyway.
+		</para>
+	    </listitem>
+	    <listitem>
+		<para>
+		    CANCEL_TAG similarly enables strict matching of CANCELs 
+		    including to-tags--act of mercy to UACs, who screw up
+		    the to-tags (however, it still depends on how forgiving
+		    the downstream UAS is). Like with ACK_TAG, all this
+		    complex transactions matching goes with <ulink
+			url="http://www.ietf.org/rfc/rfc3261.txt">RFC3261</ulink>'s
+		    magic cookie away anyway.
+		</para>
+	    </listitem>
+	</itemizedlist>
+    </section>
+    <section>
+	<title>Functions</title>
+	<section>
+	    <title>
+		<function>register_tmcb(cb_type, cb_func)</function>
+	    </title>
+	    <para>
+		For programmatic use only--register a function to be called
+		back on an event. See t_hooks.h for more details.
+	    </para>
+	    <para>Meaning of the parameters is as follows:</para>
+	    <itemizedlist>
+		<listitem>
+		    <para><emphasis>cb_type</emphasis> - Callback type.
+		    </para>
+		</listitem>
+		<listitem>
+		    <para><emphasis>cb_func</emphasis> - Callback function.
+		    </para>
+		</listitem>
+	    </itemizedlist>
+	</section>
+	
+	<section id="load_tm">
+	    <title>
+		<function>load_tm(*import_structure)</function>
+	    </title>
+	    <para>
+		For programmatic use only--import exported <acronym>TM</acronym> functions.
+		See the acc module for an example of use.
+	    </para>
+	    <para>Meaning of the parameters is as follows:</para>
+	    <itemizedlist>
+		<listitem>
+		    <para><emphasis>import_structure</emphasis> - Pointer to the import structure.
+		    </para>
+		</listitem>
+	    </itemizedlist>
+	</section>
+    </section>
+    
+</section>

modules/tm/doc/functions.xml

@@ -0,0 +1,288 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
+                      "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd">
+
+<section id="tm.functions" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <sectioninfo>
+	<revhistory>
+	    <revision>
+		<revnumber>$Revision$</revnumber>
+		<date>$Date$</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_negative">
+	<title>
+	    <function>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 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
+	    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_negative</function> usage</title>
+	    <programlisting>
+...
+route { 
+    t_on_negative("1"); 
+    t_relay(); 
+} 
+
+reply_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="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>

modules/tm/doc/params.xml

@@ -0,0 +1,191 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
+                      "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd">
+
+<section id="tm.parameters" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <sectioninfo>
+	<revhistory>
+	    <revision>
+		<revnumber>$Revision$</revnumber>
+		<date>$Date$</date>
+	    </revision>
+	</revhistory>
+    </sectioninfo>
+
+    <title>Parameters</title>
+
+    <section id="fr_timer">
+	<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>
+	    Default value is 30 seconds.
+	</para>
+	<example>
+	    <title>Set <varname>fr_timer</varname> parameter</title>
+	    <programlisting>
+...
+modparam("tm", "fr_timer", 10)
+...
+	    </programlisting>
+	</example>
+    </section>
+
+    <section id="fr_inv_timer">
+	<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>
+	    Default value is 120 seconds.
+	</para>
+	<example>
+	    <title>Set <varname>fr_inv_timer</varname> parameter</title>
+	    <programlisting>
+...
+modparam("tm", "fr_inv_timer", 200)
+...
+	    </programlisting>
+	</example>
+    </section>
+
+    <section id="wt_timer">
+	<title><varname>wt_timer</varname> (integer)</title>
+	<para>
+	    Time for which a transaction stays in memory to absorb delayed
+	    messages after it completed; also, when this timer hits,
+	    retransmission of local cancels is stopped (a puristic but complex
+	    behavior would be not to enter wait state until local branches are
+	    finished by a final reply or FR timer--we simplified).
+	</para>
+	<para>
+	    Default value is 5 seconds.
+	</para>
+	<example>
+	    <title>Set <varname>wt_timer</varname> parameter</title>
+	    <programlisting>
+...
+modparam("tm", "wt_timer", 10)
+...
+	    </programlisting>
+	</example>
+    </section>
+
+    <section id="delete_timer">
+	<title><varname>delete_timer</varname> (integer)</title>
+	<para>
+	    Time after which a to-be-deleted transaction currently ref-ed by a
+	    process will be tried to be deleted again.
+	</para>
+	<para>
+	    Default value is 2 seconds.
+	</para>
+	<example>
+	    <title>Set <varname>delete_timer</varname> parameter</title>
+	    <programlisting>
+...
+modparam("tm", "delete_timer", 5)
+...
+	    </programlisting>
+	</example>
+    </section>
+    
+    <section id="retr_timer1p1">
+	<title><varname>retr_timer1p1</varname> (integer)</title>
+	<para>
+	    Retransmission period.
+	</para>
+	<para>
+	    Default value is 1 second.
+	</para>
+	<example>
+	    <title>Set <varname>retr_timer1p1</varname> parameter</title>
+	    <programlisting>
+...
+modparam("tm", "retr_timer1p1", 2)
+...
+	    </programlisting>
+	</example>
+    </section>
+
+    <section id="retr_timer1p2">
+	<title><varname>retr_timer1p2</varname> (integer)</title>
+	<para>
+	    Retransmission period.
+	</para>
+	<para>
+	    Default value is 2 * <varname>retr_timer1p1</varname> second.
+	</para>
+	<example>
+	    <title>Set <varname>retr_timer1p2</varname> parameter</title>
+	    <programlisting>
+...
+modparam("tm", "retr_timer1p2", 4)
+...
+	    </programlisting>
+	</example>
+    </section>
+
+    <section id="retr_timer1p3">
+	<title><varname>retr_timer1p3</varname> (integer)</title>
+	<para>
+	    Retransmission period.
+	</para>
+	<para>
+	    Default value is 4 * <varname>retr_timer1p1</varname> second.
+	</para>
+	<example>
+	    <title>Set <varname>retr_timer1p4</varname> parameter</title>
+	    <programlisting>
+...
+modparam("tm", "retr_timer1p3", 8)
+...
+	    </programlisting>
+	</example>
+    </section>
+
+    <section id="retr_timer2">
+	<title><varname>retr_timer2</varname> (integer)</title>
+	<para>
+	    Maximum retransmission period.
+	</para>
+	<para>
+	    Default value is 4 seconds.
+	</para>
+	<example>
+	    <title>Set <varname>retr_timer2</varname> parameter</title>
+	    <programlisting>
+...
+modparam("tm", "retr_timer2", 8)
+...
+	    </programlisting>
+	</example>
+    </section>
+
+    <section id="noisy_ctimer">
+	<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>
+	    Default value is 0 (false).
+	</para>
+	<example>
+	    <title>Set <varname>noisy_ctimer</varname> parameter</title>
+	    <programlisting>
+...
+modparam("tm", "noisy_ctimer", 1)
+...
+	    </programlisting>
+	</example>
+    </section>
+
+</section>

modules/tm/doc/tm.sgml

@@ -1,52 +0,0 @@
-<!DOCTYPE Book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
-
-
-<!ENTITY user SYSTEM "tm_user.sgml">
-<!ENTITY devel SYSTEM "tm_devel.sgml">
-<!ENTITY faq SYSTEM "tm_faq.sgml">
-
-<!-- Include general SER documentation entities -->
-<!ENTITY % serentities SYSTEM "../../../doc/ser_entities.sgml">
-%serentities;
-
-]>
-
-<book>
-    <bookinfo>
-	<title>tm Module</title>
-	<productname class="trade">&sername;</productname>
-	<authorgroup>
-	    <author>
-		<firstname>Jiri</firstname>
-		<surname>Kuthan</surname>
-		<affiliation><orgname>&fhg;</orgname></affiliation>
-		<address>
-		    <email>[email protected]</email>
-		</address>
-	    </author>
-	    <editor>
-		<firstname>Jiri</firstname>
-		<surname>Kuthan</surname>
-		<address>
-		    <email>[email protected]</email>
-		</address>
-	    </editor>
-	</authorgroup>
-	<copyright>
-	    <year>2003</year>
-	    <holder>&fhg;</holder>
-	</copyright>
-	<revhistory>
-	    <revision>
-		<revnumber>$Revision$</revnumber>
-		<date>$Date$</date>
-	    </revision>
-	</revhistory>
-    </bookinfo>
-    <toc></toc>
-    
-    &user;
-    &devel;
-    &faq;
-    
-</book>

modules/tm/doc/tm.xml

@@ -0,0 +1,154 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
+                      "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd">
+
+<section id="tm" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <sectioninfo>
+	<authorgroup>
+	    <author>
+		<firstname>Jiri</firstname>
+		<surname>Kuthan</surname>
+		<affiliation><orgname>FhG FOKUS</orgname></affiliation>
+		<address>
+		    <email>[email protected]</email>
+		</address>
+	    </author>
+	</authorgroup>
+	<copyright>
+	    <year>2003</year>
+	    <holder>FhG FOKUS</holder>
+	</copyright>
+	<revhistory>
+	    <revision>
+		<revnumber>$Revision$</revnumber>
+		<date>$Date$</date>
+	    </revision>
+	</revhistory>
+    </sectioninfo>
+
+    <title>TM Module</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 and free, timers--you really
+	    need to be careful when you do anything. To simplify
+	    <acronym>TM</acronym> programming, there is the instrument of
+	    callbacks. The callback mechanisms allow programmers to register
+	    their functions to specific event. See t_hooks.h for a list of
+	    possible events.
+	</para>
+	<para>
+	    Other things programmers may want to know is UAC--it is a very
+	    simplistic code which allows you to generate your own
+	    transactions. Particularly useful for things like NOTIFYs or
+	    <acronym>IM</acronym> gateways. The UAC takes care of all the
+	    transaction machinery: retransmissions , FR timeouts, forking, etc.
+	    See t_uac prototype in uac.h for more details. Who wants to see the
+	    transaction result may register for a callback.
+	</para>
+    </section>
+    
+    <section id="known_issues">
+	<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>
+    
+    <xi:include href="params.xml"/>
+    <xi:include href="functions.xml"/>
+    <xi:include href="api.xml"/>
+
+</section>

modules/tm/doc/tm_devel.sgml

@@ -1,106 +0,0 @@
-<!-- Module Developer's Guide -->
-
-<chapter>
-    <chapterinfo>
-	<revhistory>
-	    <revision>
-		<revnumber>$Revision$</revnumber>
-		<date>$Date$</date>
-	    </revision>
-	</revhistory>
-    </chapterinfo>
-    <title>Developer's Guide</title>
-    <para>
-	The module does not provide any sort of <acronym>API</acronym> to use in other &ser; modules.	
-    </para>
-    <section>
-	<title>Defines</title>
-	<itemizedlist>
-	    <listitem>
-		<para>
-		    ACK_TAG enables stricter matching of acknowledgments including to-tags. Without
-		    it, to-tags are ignored. It is disabled by default for two reasons: 
-		</para>
-		<itemizedlist>
-		    <listitem>
-			<para>
-			    It eliminates an unlikely race condition in which transaction's to-tag
-			    is being rewritten by a 200 OK whereas an ACK is being looked up by
-			    to-tag.
-			</para>
-		    </listitem>
-		</itemizedlist>
-		<itemizedlist>
-		    <listitem>
-			<para>
-			    It makes &uac;s happy who set wrong to-tags.
-			</para>
-		    </listitem>
-		</itemizedlist>
-		<para>
-		    It should not make a difference, as there may be only one
-		    negative reply sent upstream and 200/ACKs are not matched
-		    as they constitute another transaction. It will make no
-		    difference at all when the new magic cookie matching is
-		    enabled anyway.
-		</para>
-	    </listitem>
-	    <listitem>
-		<para>
-		    CANCEL_TAG similarly enables strict matching of CANCELs 
-		    including to-tags--act of mercy to &uac;s, who screw up
-		    the to-tags (however, it still depends on how forgiving
-		    the downstream UAS is). Like with ACK_TAG, all this
-		    complex transactions matching goes with &rfc3261;'s
-		    magic cookie away anyway.
-		</para>
-	    </listitem>
-	</itemizedlist>
-    </section>
-    <section>
-	<title>Functions</title>
-	<section>
-	    <title>
-		<function moreinfo="none">register_tmcb(cb_type, cb_func)</function>
-	    </title>
-	    <para>
-		For programmatic use only--register a function to be called back on an event. See
-		t_hooks.h for more details.
-	    </para>
-	    <para>Meaning of the parameters is as follows:</para>
-	    <itemizedlist>
-		<listitem>
-		    <para><emphasis>cb_type</emphasis> - Callback type.
-		    </para>
-		</listitem>
-		<listitem>
-		    <para><emphasis>cb_func</emphasis> - Callback function.
-		    </para>
-		</listitem>
-	    </itemizedlist>
-	</section>
-
-	<section>
-	    <title>
-		<function moreinfo="none">load_tm(*import_structure)</function>
-	    </title>
-	    <para>
-		For programmatic use only--import exported <acronym>TM</acronym> functions.
-		See the acc module for an example of use.
-	    </para>
-	    <para>Meaning of the parameters is as follows:</para>
-	    <itemizedlist>
-		<listitem>
-		    <para><emphasis>import_structure</emphasis> - Pointer to the import structure.
-		    </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:
--->

modules/tm/doc/tm_faq.sgml

@@ -1,67 +0,0 @@
-<!-- Module FAQ -->
-
-<chapter>
-    <chapterinfo>
-	<revhistory>
-	    <revision>
-		<revnumber>$Revision$</revnumber>
-		<date>$Date$</date>
-	    </revision>
-	</revhistory>
-    </chapterinfo>
-    <title>Frequently Asked Questions</title>
-    <qandaset defaultlabel="number">
-	<qandaentry>
-	    <question>
-		<para>Where can I find more about &ser;?</para>
-	    </question>
-	    <answer>
-		<para>
-		    Take a look at &serhomelink;.
-		</para>
-	    </answer>
-	</qandaentry>
-	<qandaentry>
-	    <question>
-		<para>Where can I post a question about this module?</para>
-	    </question>
-	    <answer>
-		<para>
-		    First at all check if your question was already answered on one of
-		    our mailing lists: 
-		</para>
-		<itemizedlist>
-		    <listitem>
-			<para>&seruserslink;</para>
-		    </listitem>
-		    <listitem>
-			<para>&serdevlink;</para>
-		    </listitem>
-		</itemizedlist>
-		<para>
-		    E-mails regarding any stable version should be sent to &serusersmail; and e-mail
-		    regarding development versions or CVS snapshots should be send to &serdevmail;.
-		</para>
-		<para>
-		    If you want to keep the mail private, send it to &serhelpmail;.
-		</para>
-	    </answer>
-	</qandaentry>
-	<qandaentry>
-	    <question>
-		<para>How can I report a bug?</para>
-	    </question>
-	    <answer>
-		<para>
-		    Please follow the guidelines provided at: &serbugslink;
-		</para>
-	    </answer>
-	</qandaentry>
-    </qandaset>
-</chapter>
-
-<!-- Keep this element at the end of the file
-Local Variables:
-sgml-parent-document: ("tm.sgml" "Book" "chapter")
-End:
--->

modules/tm/doc/tm_user.sgml

@@ -1,669 +0,0 @@
-<!-- Module User's Guide -->
-
-<chapter>
-    <chapterinfo>
-	<revhistory>
-	    <revision>
-		<revnumber>$Revision$</revnumber>
-		<date>$Date$</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>
-    <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>
-	    </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_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 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_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 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_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 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:[email protected]
-sip:[email protected]
-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:
--->