- docbook documentation.

modules/tm/README

@@ -1,245 +1,473 @@
-#
-# $Id$
-#
-# TM Module README
-#
-# Module depends on: none
-#
-
-TM Module enables stateful processing of SIP transactions.
-The main use of stateful logic, which is costly in terms of
-memory and CPU, 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 CPU caused by 
-retransmission processing for memory. That makes however only
-sense if CPU consumption per request is huge. For example,
-if you want to avoid costly DNS resolution for every retransmission
-of a request to an unresolveable destination, use stateful mode.
-Then, only the initial message burdens server by DNS queries,
-subsequent retranmissions will be dropped and will not result in
-more processes blocked by DNS resolution. The price is more 
-memory consumption and higher processing latency.
-
-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.
-
-In general, if TM is used, it copies clones of received SIP
-messages in shared memory. That costs the memory and also CPU
-time (memcpys, lookups, shmem locks, etc.) Note that non-TM
-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 addRecordRoute *after* t_relay
-is pretty useless, as the RR is added to privately held message
-whereas its TM clone is being forwarded.
-
-TM 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 TM 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.
-
-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
-IM 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.
-
-Exported parameters:
---------------------
-
-Name:		fr_timer
-Type:		int (seconds)
-Default:	FR_TIME_OUT=30
-Desc:		timer which hits if no final reply for a request or
-			ACK for a negative INVITE reply arrives
-
-Name:		fr_inv_timer
-Type:		int(seconds)
-Default:	INV_FR_TIME_OUT=120
-Desc:		timer which hits if no final reply for an INVITE
-			arrives after a provisional message was received
-
-Name:		wt_timer
-Type:		int (seconds)
-Default:	WT_TIME_OUT=5
-Desc:		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)
-
-Name:		delete_timer
-Type:		int (seconds)
-Default:	DEL_TIME_OUT=2
-Desc:		time after which a to-be-deleted transaction currently
-			ref-ed by a process will be tried to be deleted again
-
-Name:		retr_timer1p1, 2, 3
-Type:		int (seconds)
-Default:	RETR_T1=1, 2*RETR_T1, 4*RETR_T1
-Desc:		retransmission period
-
-Name:		retr_timer2
-Type:		int (seconds)
-Default:	RETR_T2=4
-Desc:		maximum retransmission period
-
-Name:		noisy_ctimer
-Type:		int (boolean)
-Default:	0 (FALSE)
-Desc:		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)
-
-Exported Functions:
--------------------
-
-For use in scripts, t_relay_to and t_relay are design. All other
-functions are advanced and should be used with care.
-
-Name: 	t_relay_to
-Params:	ip address, port number
-Desc:	relay a message statefuly to a fixed destination; this along with
-		t_relay is the function most users want to use -- all other are
-		mostly for programming; programmers interested in writing TM
-		logic should review how t_relay is implemented in tm.c and how
-		TM callbacks work
-
-Name:	t_relay
-Params:	0
-Desc:	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
-Example: if (!t_relay()) { sl_reply_error(); break; };
-
-Name:	t_on_negative
-Params:	reply_route
-Desc:	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 "202 I will take care of it"); 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 (t_reply). 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.
-Example: route { t_on_negative("1"); t_relay(); } reply_route[1] {
-			revert_uri(); setuser("voicemail"); append_branch(); }
-
-		see test/onr.cfg for a more complex example of combination
-		of serial with parallel forking
-
-
-Name:	append_branch (actually part of core now)
-Params:	uri
-Desc:	adds a new destination to destination set; if used,
-		a subsequent call to t_relay (or t_forward_nonack, 
-		on which t_relay is based) than introduces
-	    a new branch and forks a transaction; append_branch may
-		also be called from reply processing -- this may 
-	    be particularly useful for services such as
-		"fork_on_no_reply"
-
-Name:	append_branch
-Params:	0
-Desc:	similarly to t_fork_to, it extends destination set
-		by a new entry; the difference is that current uri
-		is taken as new entry;
-Example: set_user("john"); t_fork(); set_user("alice");
-		 t_fork(); t_relay();
-
------   ----  ---- medium-advanced commands here --- on -----
-
-Name:	t_newtran
-Params: 0
-Desc:	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
-Example: see test/uas.cfg: 
-	    if (t_newtran()) { log("UAS logic"); t_reply("999","hello"); }
-		else sl_reply_error();
-
-Name:	t_reply
-Params:	code, reason phrase
-Desc: 	sends a stateful reply after a transaction has been
-		established; see t_newtran for usage; 
-
------ only --- advanced --- commands --- from --- here --- on -----
-
-Name:	t_lookup_request
-Params:	0
-Desc:	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 t_newtran
-
-
-Name:	t_retransmit_reply
-Params:	0
-Desc:	retransmits a reply sent previously by UAS transaction
-
-Name:	t_release
-Params:	0
-Desc:	remove transaction from memory (it will be first put on
-		a wait timer to absorb delayed messages)
-
-Name:	t_forward_nonack
-Params:	ip, port
-Desc:	mainly for internal -- forward a non-ACK request statefuly
-
-Name:	register_tmcb
-Params:	callback type, callback function
-Desc:	for programmatic use only -- register a function to be called
-		back on an event; see t_hooks.h for more details
-
-Name:	load_tm
-Params:	*import_structure
-Desc:	for programmatic use only -- import exported TM functions;
-		see the acc module for an example of use
-
-
-External Usage of TM
----------------------
-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
-FIFO server with configuration option
-	fifo="/tmp/ser_fifo"
-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
 
+tm Module
+
+Jiri Kuthan
+
+   FhG FOKUS
+
+Edited by
+
+Jiri Kuthan
+
+   Copyright © 2003 FhG FOKUS
+     _________________________________________________________
+
+   Table of Contents
+   1. User's Guide
+
+        1.1. Overview
+        1.2. Dependencies
+
+              1.2.1. SER Modules
+              1.2.2. External Libraries or Applications
+
+        1.3. Exported Parameters
+
+              1.3.1. fr_timer (integer)
+              1.3.2. fr_inv_timer (integer)
+              1.3.3. wt_timer (integer)
+              1.3.4. delete_timer (integer)
+              1.3.5. retr_timer1p1 (integer)
+              1.3.6. retr_timer1p2 (integer)
+              1.3.7. retr_timer1p3 (integer)
+              1.3.8. retr_timer2 (integer)
+              1.3.9. noisy_ctimer (integer)
+
+        1.4. Exported Functions
+
+              1.4.1. t_relay_to(ip, port)
+              1.4.2. t_relay()
+              1.4.3. t_on_negative(reply_route)
+              1.4.4. append_branch()
+              1.4.5. t_newtran()
+              1.4.6. t_reply(code, reason_phrase)
+              1.4.7. t_lookup_request()
+              1.4.8. t_retransmit_reply()
+              1.4.9. t_release()
+              1.4.10. t_forward_nonack(ip, port)
+              1.4.11. External Usage of TM
+              1.4.12. Known Issues
+
+   2. Developer's Guide
+
+        2.1. Defines
+        2.2. Functions
+
+              2.2.1. register_tmcb(cb_type, cb_func)
+              2.2.2. load_tm(*import_structure)
+
+   3. Frequently Asked Questions
+
+   List of Examples
+   1-1. Set fr_timer parameter
+   1-2. Set fr_inv_timer parameter
+   1-3. Set wt_timer parameter
+   1-4. Set delete_timer parameter
+   1-5. Set retr_timer1p1 parameter
+   1-6. Set retr_timer1p2 parameter
+   1-7. Set retr_timer1p4 parameter
+   1-8. Set retr_timer2 parameter
+   1-9. Set noisy_ctimer parameter
+   1-10. t_relay_to usage
+   1-11. t_relay usage
+   1-12. t_on_negative usage
+   1-13. append_branch usage
+   1-14. t_newtran usage
+   1-15. t_reply usage
+   1-16. t_lookup_request usage
+   1-17. t_retransmit_reply usage
+   1-18. t_release usage
+   1-19. t_forward_nonack usage
+     _________________________________________________________
+
+Chapter 1. User's Guide
+
+1.1. Overview
+
+   TM module enables stateful processing of SIP transactions. The
+   main use of stateful logic, which is costly in terms of memory
+   and CPU, 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 CPU caused by retransmission
+   processing for memory. That makes however only sense if CPU
+   consumption per request is huge. For example, if you want to
+   avoid costly DNS resolution for every retransmission of a
+   request to an unresolveable destination, use stateful mode.
+   Then, only the initial message burdens server by DNS queries,
+   subsequent retranmissions will be dropped and will not result
+   in more processes blocked by DNS resolution. The price is more
+   memory consumption and higher processing latency.
+
+   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.
+
+   In general, if TM is used, it copies clones of received SIP
+   messages in shared memory. That costs the memory and also CPU
+   time (memcpys, lookups, shmem locks, etc.) Note that non-TM
+   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 after t_relay is
+   pretty useless, as the RR is added to privately held message
+   whereas its TM clone is being forwarded.
+
+   TM 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 TM 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.
+
+   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
+   IM 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.
+     _________________________________________________________
+
+1.2. Dependencies
+
+1.2.1. SER Modules
+
+   The following modules must be loaded before this module:
+
+     * No dependencies on other SER modules.
+     _________________________________________________________
+
+1.2.2. External Libraries or Applications
+
+   The following libraries or applications must be installed
+   before running SER with this module loaded:
+
+     * None.
+     _________________________________________________________
+
+1.3. Exported Parameters
+
+1.3.1. fr_timer (integer)
+
+   Timer which hits if no final reply for a request or ACK for a
+   negative INVITE reply arrives (in seconds).
+
+   Default value is 30 seconds. 
+
+   Example 1-1. Set fr_timer parameter
+...
+modparam("tm", "fr_timer", 10)
+...
+     _________________________________________________________
+
+1.3.2. fr_inv_timer (integer)
+
+   Timer which hits if no final reply for an INVITE arrives after
+   a provisional message was received (in seconds).
+
+   Default value is 120 seconds. 
+
+   Example 1-2. Set fr_inv_timer parameter
+...
+modparam("tm", "fr_inv_timer", 200)
+...
+     _________________________________________________________
+
+1.3.3. wt_timer (integer)
+
+   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).
+
+   Default value is 5 seconds. 
+
+   Example 1-3. Set wt_timer parameter
+...
+modparam("tm", "wt_timer", 10)
+...
+     _________________________________________________________
+
+1.3.4. delete_timer (integer)
+
+   Time after which a to-be-deleted transaction currently ref-ed
+   by a process will be tried to be deleted again.
+
+   Default value is 2 seconds. 
+
+   Example 1-4. Set delete_timer parameter
+...
+modparam("tm", "delete_timer", 5)
+...
+     _________________________________________________________
+
+1.3.5. retr_timer1p1 (integer)
+
+   Retransmission period.
+
+   Default value is 1 second. 
+
+   Example 1-5. Set retr_timer1p1 parameter
+...
+modparam("tm", "retr_timer1p1", 2)
+...
+     _________________________________________________________
+
+1.3.6. retr_timer1p2 (integer)
+
+   Retransmission period.
+
+   Default value is 2 * retr_timer1p1 second. 
+
+   Example 1-6. Set retr_timer1p2 parameter
+...
+modparam("tm", "retr_timer1p2", 4)
+...
+     _________________________________________________________
+
+1.3.7. retr_timer1p3 (integer)
+
+   Retransmission period.
+
+   Default value is 4 * retr_timer1p1 second. 
+
+   Example 1-7. Set retr_timer1p4 parameter
+...
+modparam("tm", "retr_timer1p3", 8)
+...
+     _________________________________________________________
+
+1.3.8. retr_timer2 (integer)
+
+   Maximum retransmission period.
+
+   Default value is 4 seconds. 
+
+   Example 1-8. Set retr_timer2 parameter
+...
+modparam("tm", "retr_timer2", 8)
+...
+     _________________________________________________________
+
+1.3.9. noisy_ctimer (integer)
+
+   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).
+
+   Default value is 0 (false). 
+
+   Example 1-9. Set noisy_ctimer parameter
+...
+modparam("tm", "noisy_ctimer", 1)
+...
+     _________________________________________________________
+
+1.4. Exported Functions
+
+1.4.1. t_relay_to(ip, port)
+
+   Relay a message statefuly to a fixed destination. This along
+   with t_relay is the function most users want to use--all other
+   are mostly for programming. Programmers interested in writing
+   TM logic should review how t_relay is implemented in tm.c and
+   how TM callbacks work.
+
+   Meaning of the parameters is as follows:
+
+     * ip - IP address where the message should be sent.
+     * port - Port number.
+
+   Example 1-10. t_relay_to usage
+...
+t_relay_to("1.2.3.4", "5060");
+...
+     _________________________________________________________
+
+1.4.2. t_relay()
+
+   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.
+
+   Example 1-11. t_relay usage
+...
+if (!t_relay()) { sl_reply_error(); break; };
+...
+     _________________________________________________________
+
+1.4.3. t_on_negative(reply_route)
+
+   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 "202 I will take care
+   of it"). 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 (t_reply).
+   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.
+
+   Meaning of the parameters is as follows:
+
+     * reply_route - Reply route block to be called.
+
+   Example 1-12. t_on_negative usage
+...
+route {
+    t_on_negative("1");
+    t_relay();
+}
+
+reply_route[1] {
+    revert_uri();
+    setuser("voicemail");
+    append_branch();
+}
+...
+
+   See test/onr.cfg for a more complex example of combination of
+   serial with parallel forking.
+     _________________________________________________________
+
+1.4.4. append_branch()
+
+   Similarly to t_fork_to, it extends destination set by a new
+   entry. The difference is that current URI is taken as new
+   entry.
+
+   Example 1-13. append_branch usage
+...
+set_user("john");
+t_fork();
+set_user("alice");
+t_fork();
+t_relay();
+...
+     _________________________________________________________
+
+1.4.5. t_newtran()
+
+   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.
+
+   Example 1-14. t_newtran usage
+...
+if (t_newtran()) {
+    log("UAS logic");
+    t_reply("999","hello");
+} else sl_reply_error();
+...
+
+   See test/uas.cfg for more examples.
+     _________________________________________________________
+
+1.4.6. t_reply(code, reason_phrase)
+
+   Sends a stateful reply after a transaction has been
+   established. See t_newtran for usage.
+
+   Meaning of the parameters is as follows:
+
+     * code - Reply code number.
+     * reason_phrase - Reason string.
+
+   Example 1-15. t_reply usage
+...
+t_reply("404", "Not found");
+...
+     _________________________________________________________
+
+1.4.7. t_lookup_request()
+
+   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 t_newtran.
+
+   Example 1-16. t_lookup_request usage
+...
+if (t_lookup_request()) {
+    ...
+};
+...
+     _________________________________________________________
+
+1.4.8. t_retransmit_reply()
+
+   Retransmits a reply sent previously by UAS transaction.
+
+   Example 1-17. t_retransmit_reply usage
+...
+t_retransmit_reply();
+...
+     _________________________________________________________
+
+1.4.9. t_release()
+
+   Remove transaction from memory (it will be first put on a wait
+   timer to absorb delayed messages).
+
+   Example 1-18. t_release usage
+...
+t_release();
+...
+     _________________________________________________________
+
+1.4.10. t_forward_nonack(ip, port)
+
+   mainly for internal usage--forward a non-ACK request
+   statefuly.
+
+   Meaning of the parameters is as follows:
+
+     * ip - IP address where the message should be sent.
+     * port - Port number.
+
+   Example 1-19. t_forward_nonack usage
+...
+t_forward_nonack("1.2.3.4", "5060");
+...
+     _________________________________________________________
+
+1.4.11. External Usage of TM
+
+   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 FIFO
+   server with configuration option.
+
+   fifo="/tmp/ser_fifo"
+
+   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
  :t_uac_from:[<file_name>]\n
  <method>\n
  <sender's uri>\n
@@ -249,15 +477,12 @@ must follow very simple format, which is
  .\n
  \n
 
-(Filename is to where a report will be dumped. ser assumes /tmp
-as file's directory.)
+   (Filename is to where a report will be dumped. ser assumes
+   /tmp as file's directory.)
 
-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:
----
+   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:
 [jiri@bat jiri]$ cat > /tmp/ser_fifo
 :t_uac_from:xxx
 MESSAGE
@@ -273,58 +498,111 @@ yet body
 end of body
 .
 
-or cat test/transaction.fifo > /tmp/ser_fifo
-
-Defines
--------
-- ACK_TAG enables stricter matching of acknowledgemnts including to-tags;
-  without it, to-tags are ignored; it is disabled by default for two reasons:
-  a) 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
-  b) it makes UACs happy who set wrong to-tags
-
-  It should not make a difference, as there may be only one
-  negative reply sent upstream and 200/ACKs are not matched
-  as they consititute another transaction. It will make no
-  difference at all when the new magic cookie matching is
-  enabled anyway.
-- 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 RFC3261's
-  magic cookie away anyway
-
-
-
-Known Issues
------------
-- we don't have authentication merging on forking
-- local ACK/CANCELs copy'n'pastes Route and ignores deleted
-  Routes
-- 6xx should be delayed
-- 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)
-- another performance improvement may be achieved by not parsing
-  CSeq in replies until reply branch matches branch of an INVITE/CANCEL
-  in transaction table
-- t_replicate 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)
-- SNMP support (as nobody cares about SNMP, in particular for TM, I will
-  drop this item soon)
-
-
- * ***************************************************
- *             IMPORTANT NOTE
- *
- *    All UACs but t_uac_dlg are being deprecated now
- *    and will be removed from future versions of TM
- *    module. Eliminate all dependancies on them asap.
- *
- * ****************************************************
+   or cat test/transaction.fifo > /tmp/ser_fifo
+     _________________________________________________________
+
+1.4.12. Known Issues
+
+     * We don't have authentication merging on forking.
+     * Local ACK/CANCELs copy'n'pastes Route and ignores deleted
+       Routes.
+     * 6xx should be delayed.
+     * 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).
+     * Another performance improvement may be achieved by not
+       parsing CSeq in replies until reply branch matches branch
+       of an INVITE/CANCEL in transaction table.
+     * t_replicate 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).
+     * SNMP support (as nobody cares about SNMP, in particular
+       for TM, I will drop this item soon).
+     _________________________________________________________
+
+Chapter 2. Developer's Guide
+
+   The module does not provide any sort of API to use in other
+   SER modules.
+     _________________________________________________________
+
+2.1. Defines
+
+     * ACK_TAG enables stricter matching of acknowledgemnts
+       including to-tags. Without it, to-tags are ignored. It is
+       disabled by default for two reasons:
+          + 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.
+          + It makes UACs happy who set wrong to-tags.
+       It should not make a difference, as there may be only one
+       negative reply sent upstream and 200/ACKs are not matched
+       as they consititute another transaction. It will make no
+       difference at all when the new magic cookie matching is
+       enabled anyway.
+     * 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 RFC3261's magic cookie
+       away anyway.
+     _________________________________________________________
+
+2.2. Functions
+
+2.2.1. register_tmcb(cb_type, cb_func)
+
+   For programmatic use only--register a function to be called
+   back on an event. See t_hooks.h for more details.
+
+   Meaning of the parameters is as follows:
+
+     * cb_type - Callback type.
+     * cb_func - Callback function.
+     _________________________________________________________
+
+2.2.2. load_tm(*import_structure)
+
+   For programmatic use only--import exported TM functions. See
+   the acc module for an example of use.
+
+   Meaning of the parameters is as follows:
+
+     * import_structure - Pointer to the import structure.
+     _________________________________________________________
+
+Chapter 3. Frequently Asked Questions
+
+   3.1. Where can I find more about SER?
+   3.2. Where can I post a question about this module?
+   3.3. How can I report a bug?
+
+   3.1. Where can I find more about SER?
+
+   Take a look at http://iptel.org/ser.
+
+   3.2. Where can I post a question about this module?
+
+   First at all check if your question was already answered on
+   one of our mailing lists:
+
+     * http://mail.iptel.org/mailman/listinfo/serusers
+     * http://mail.iptel.org/mailman/listinfo/serdev
+
+   E-mails regarding any stable version should be sent to
+   <[email protected]> and e-mail regarding development versions
+   or CVS snapshots should be send to <[email protected]>.
+
+   If you want to keep the mail private, send it to
+   <[email protected]>.
+
+   3.3. How can I report a bug?
+
+   Please follow the guidelines provided at:
+   http://iptel.org/ser/bugs

modules/tm/doc/tm.sgml

@@ -0,0 +1,52 @@
+<!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_devel.sgml

@@ -0,0 +1,106 @@
+<!-- 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 acknowledgemnts 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 consititute 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

@@ -0,0 +1,67 @@
+<!-- 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

@@ -0,0 +1,666 @@
+<!-- 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 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:[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:
+-->