- doc update:

  - fixed timer examples (milliseconds instead of seconds)
  - added note that delete_timer is obsolete for 2.1
  - added "See also" for various parameters and functions
  - added missing docs for: t_reset_fr(), t_reset_retr(),
  t_set_max_lifetime(), t_reset_max_lifetime(), t_set_auto_inv_100(),
  max_inv_lifetime, max_noninv_lifetime, restart_fr_on_each_reply,
  auto_inv_100
  - removed solved "known limitations": authentication mergin on forking
  (we have it), local ack/cancel ignoring delete routes (Miklos reparse*
   patches solved it some time ago), 6xx should be delayed (solved long time
   ago), snmp support (we don't intend to ever add it).
- regenerated the README

modules/tm/README

@@ -60,9 +60,6 @@ Overview
 
 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
@@ -76,8 +73,6 @@ Known Issues
      * 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).
 
 Parameters
 
@@ -89,11 +84,13 @@ fr_timer (integer)
    Timer which hits if no final reply for a request or ACK for a negative
    INVITE reply arrives (in milliseconds).
 
-   Default value is 30 seconds.
+   Default value is 30000 ms (30 seconds).
+
+   See also: t_set_fr(), max_noninv_lifetime.
 
    Example 1. Set fr_timer parameter
 ...
-modparam("tm", "fr_timer", 10)
+modparam("tm", "fr_timer", 10000)
 ...
 
 fr_inv_timer (integer)
@@ -101,38 +98,112 @@ fr_inv_timer (integer)
    Timer which hits if no final reply for an INVITE arrives after a
    provisional message was received (in milliseconds).
 
-   Default value is 120 seconds.
+   Note: this timer can be restarted when a provisional response is
+   received. For more details see restart_fr_on_each_reply.
+
+   Default value is 120000 ms (120 seconds).
+
+   See also: t_set_fr(), max_inv_lifetime.
 
    Example 2. Set fr_inv_timer parameter
 ...
-modparam("tm", "fr_inv_timer", 200)
+modparam("tm", "fr_inv_timer", 180000)
+...
+
+max_inv_lifetime (integer)
+
+   Maximum time an INVITE transaction is allowed to be active (in
+   milliseconds). After this interval has passed from the transaction
+   creation, the transaction will be either moved into the wait state or
+   in the final response retransmission state, irrespective of the
+   transaction fr_inv_timer and fr_timer values.
+
+   An INVITE transaction will be kept in memory for maximum:
+   max_inv_lifetime+fr_timer(from the ack to the final reply
+   wait)+wt_timer.
+
+   The main difference between this timer and fr_inv_timer is that the
+   fr_inv_timer is per branch, while max_inv_lifetime is per the whole
+   transaction. Even on a per branch basis fr_inv_timer could be
+   restarted. For example, by default if restart_fr_on_each_reply is not
+   cleared, the fr_inv_timer will be restarted for each received
+   provisional reply. Even if restart_fr_on_each_reply is not set the
+   fr_inv_timer will still be restarted for each increasing reply (e.g.
+   180, 181, 182, ...). Another example when a transaction can live
+   substantially more then its fr_inv_timer and where max_inv_lifetime
+   will help is when dns failover is used (each failed dns destination can
+   introduce a new branch).
+
+   The default value is 180000 ms (180 seconds - the rfc3261 timer C
+   value).
+
+   See also: max_noninv_lifetime, t_set_max_lifetime() (allows changing
+   max_inv_lifetime on a per transaction basis), t_reset_max_lifetime
+   fr_timer, wt_timer, restart_fr_on_each_reply.
+
+   Example 3. Set max_inv_lifetime parameter
+...
+modparam("tm", "max_inv_lifetime", 150000)
+...
+
+max_noninv_lifetime (integer)
+
+   Maximum time a non-INVITE transaction is allowed to be active (in
+   milliseconds). After this interval has passed from the transaction
+   creation, the transaction will be either moved into the wait state or
+   in the final response retransmission state, irrespective of the
+   transaction fr_timer value. It's the same as max_inv_lifetime, but for
+   non-INVITEs.
+
+   A non-INVITE transaction will be kept in memory for maximum:
+   max_noninv_lifetime+wt_timer.
+
+   The main difference between this timer and fr_timer is that the
+   fr_timer is per branch, while max_noninv_lifetime is per the whole
+   transaction. An example when a transaction can live substantially more
+   then its fr_timer and where max_noninv_lifetime will help is when dns
+   failover is used (each failed dns destination can introduce a new
+   branch).
+
+   The default value is 32000 ms (32 seconds - the rfc3261 timer F value).
+
+   See also: max_inv_lifetime, t_set_max_lifetime() (allows changing
+   max_noninv_lifetime on a per transaction basis), t_reset_max_lifetime
+   fr_timer, wt_timer.
+
+   Example 4. Set max_noninv_lifetime parameter
+...
+modparam("tm", "max_inv_lifetime", 30000)
 ...
 
 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 behavior would be not to
-   enter wait state until local branches are finished by a final reply or
-   FR timer--we simplified).
+   after it completed (in milliseconds); 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).
 
-   Default value is 5 seconds.
+   Default value is 5000 ms (5 seconds).
 
-   Example 3. Set wt_timer parameter
+   Example 5. Set wt_timer parameter
 ...
-modparam("tm", "wt_timer", 10)
+modparam("tm", "wt_timer", 1000)
 ...
 
 delete_timer (integer)
 
    Time after which a to-be-deleted transaction currently ref-ed by a
-   process will be tried to be deleted again.
+   process will be tried to be deleted again (in milliseconds).
+
+   Note: this parameter is obsolete for ser 2.1 (in 2.1 the transaction is
+   deleted the moment it's not referenced anymore).
 
    Default value is 200 milliseconds.
 
-   Example 4. Set delete_timer parameter
+   Example 6. Set delete_timer parameter
 ...
-modparam("tm", "delete_timer", 5)
+modparam("tm", "delete_timer", 100)
 ...
 
 retr_timer1 (integer)
@@ -141,7 +212,7 @@ retr_timer1 (integer)
 
    Default value is 500 milliseconds.
 
-   Example 5. Set retr_timer1 parameter
+   Example 7. Set retr_timer1 parameter
 ...
 modparam("tm", "retr_timer1", 1000)
 ...
@@ -154,7 +225,7 @@ retr_timer2 (integer)
 
    Default value is 4000 milliseconds.
 
-   Example 6. Set retr_timer2 parameter
+   Example 8. Set retr_timer2 parameter
 ...
 modparam("tm", "retr_timer2", 2000)
 ...
@@ -169,15 +240,57 @@ noisy_ctimer (integer)
    some functionality explicitly turned it on for a transaction (like acc
    does to avoid unaccounted transactions due to expired timer). Turn this
    off only if you know the client UACs will timeout and their timeout
-   interval fro INVITEs is lower or equal than tm's fr_inv_timer.
+   interval for INVITEs is lower or equal than tm's fr_inv_timer.
 
    Default value is 1 (on).
 
-   Example 7. Set noisy_ctimer parameter
+   Example 9. Set noisy_ctimer parameter
 ...
 modparam("tm", "noisy_ctimer", 1)
 ...
 
+restart_fr_on_each_reply (integer)
+
+   If set (default), the fr_inv_timer for an INVITE transaction will be
+   restarted for each provisional reply received (rfc3261 mandated
+   behaviour). If not set, the fr_inv_timer will be restarted only for the
+   first provisional replies and for increasing replies greater or equal
+   180 (e.g. 180, 181, 182, 185, ...).
+
+   Setting it to 0 is especially useful when dealing with bad UAs that
+   continuously retransmit 180s, not allowing the transaction to timeout
+   (and thus making impossible the implementation of certain services,
+   like automatic voicemail after x seconds).
+
+   Default value is 1 (on).
+
+   See also: fr_inv_timer, max_inv_lifetime.
+
+   Example 10. Set restart_fr_on_each_reply parameter
+...
+modparam("tm", "restart_fr_on_each_reply", 0)
+...
+
+auto_inv_100 (integer)
+
+   If set (default) tm will automatically send and 100 reply to INVITEs.
+
+   Setting it to 0 one can be used to enable doing first some tests or
+   pre-processing on the INVITE and only if some conditions are met
+   manually send a 100 (using t_reply()). Note however that in this case
+   all the 100s have to be sent "by hand". t_set_auto_inv_100() might help
+   to selectively turn off this feature only for some specific
+   transactions.
+
+   Default value is 1 (on).
+
+   See also: t_set_auto_inv_100().
+
+   Example 11. Set auto_inv_100 parameter
+...
+modparam("tm", "auto_inv_100", 0)
+...
+
 unix_tx_timeout (integer)
 
    Unix socket transmission timeout, in milliseconds.
@@ -188,7 +301,7 @@ unix_tx_timeout (integer)
 
    The default value is 500 milliseconds.
 
-   Example 8. Set unix_tx_timeout parameter
+   Example 12. Set unix_tx_timeout parameter
 ...
 modparam("tm", "unix_tx_timeout", 250)
 ...
@@ -205,7 +318,7 @@ aggregate_challenges (integer)
 
    Default value is 1 (required by rfc3261).
 
-   Example 9. Set aggregate_challenges parameter
+   Example 13. Set aggregate_challenges parameter
 ...
 modparam("tm", "aggregate_challenges", 0)
 ...
@@ -231,7 +344,7 @@ reparse_invite (integer)
 
    Default value is 1.
 
-   Example 10. Set reparse_invite parameter
+   Example 14. Set reparse_invite parameter
 ...
 modparam("tm", "reparse_invite", 0)
 ...
@@ -249,7 +362,7 @@ ac_extra_hdrs (string)
 
    Default value is "".
 
-   Example 11. Set ac_extra_hdrs parameter
+   Example 15. Set ac_extra_hdrs parameter
 ...
 modparam("tm", "ac_extra_hdrs", "myfavoriteheaders-")
 ...
@@ -267,7 +380,7 @@ blst_503 (integer)
 
    The default value is 0 (disabled due to the reasons above).
 
-   Example 12. Set blst_503 parameter
+   Example 16. Set blst_503 parameter
 ...
 modparam("tm", "blst_503", 1)
 ...
@@ -282,7 +395,7 @@ blst_503_def_timeout (integer)
    present, the 503 reply source will not be blacklisted (rfc conformant
    behaviour).
 
-   Example 13. Set blst_503_def_timeout parameter
+   Example 17. Set blst_503_def_timeout parameter
 ...
 modparam("tm", "blst_503_def_timeout", 120)
 ...
@@ -296,7 +409,7 @@ blst_503_min_timeout (integer)
 
    The default value is 0
 
-   Example 14. Set blst_503_min_timeout parameter
+   Example 18. Set blst_503_min_timeout parameter
 ...
 modparam("tm", "blst_503_min_timeout", 30)
 ...
@@ -310,7 +423,7 @@ blst_503_max_timeout (integer)
 
    The default value is 3600
 
-   Example 15. Set blst_503_max_timeout parameter
+   Example 19. Set blst_503_max_timeout parameter
 ...
 modparam("tm", "blst_503_max_timeout", 604800)
 ...
@@ -334,7 +447,7 @@ blst_methods_add (unsigned integer)
 
    The default value is 1, only INVITEs trigger blacklisting
 
-   Example 16. Set blst_methods_add parameter
+   Example 20. Set blst_methods_add parameter
 ...
 # INVITEs and REGISTERs trigger blacklisting
 modparam("tm", "blst_methods_add", 33)
@@ -348,7 +461,7 @@ blst_methods_lookup (unsigned integer)
    The default value is 4294967287, every method type except BYE. (We try
    to deliver BYEs no matter what)
 
-   Example 17. Set blst_methods_lookup parameter
+   Example 21. Set blst_methods_lookup parameter
 ...
 # lookup only INVITEs
 modparam("tm", "blst_methods_lookup", 1)
@@ -360,7 +473,7 @@ cancel_b_method (integer)
    (a branch where no reply greater the 99 was received). The possible
    values are 0, 1, and 2.
 
-   0 will immediately stop the request (INVITE) retrasmission on the
+   0 will immediately stop the request (INVITE) retransmission on the
    branch and it will behave as if the branch was immediately replied with
    a 487 (a fake internal 487 reply). The advantage is the unreplied
    branches will be terminated immediately. However it introduces a race
@@ -387,41 +500,108 @@ cancel_b_method (integer)
 
    The default value is 1.
 
-   Example 18. Set cancel_b_method parameter
+   Example 22. Set cancel_b_method parameter
 ...
 modparam("tm", "cancel_b_method", 1)
 ...
 
+reparse_on_dns_failover (integer)
+
+   If set to 1, the SIP message after a DNS failover is constructed from
+   the outgoing message buffer of the failed branch instead of from the
+   received request.
+
+   It must be set if multiple branches are installed, the SIP message is
+   modified differently in them, and at least one of them can result in
+   DNS failover. If the parameter is not set the per-branch modifications
+   are lost after the failover.
+
+   Note: If the parameter is set, branch route block and
+   TMCB_REQUEST_FWDED callback are not called in case of the failover.
+
+   Disadvantage: only the via header is replaced in the message buffer, so
+   the outgoing socket address is not corrected in any other part of the
+   message. It is dangerous on multihomed hosts: when the new SIP request
+   after the DNS failover is sent via different interface than the first
+   request, the message can contain incorrect ip address in the
+   Record-Route header for instance.
+
+   Default value is 1.
+
+   Example 23. Set reparse_on_dns_failover parameter
+...
+modparam("tm", "reparse_on_dns_failover", 0)
+...
+
+on_sl_reply (string)
+
+   Sets reply route block, to which control is passed when a reply is
+   received that has no associated transaction. The reply is passed to the
+   core for stateless forwarding after the route block execution unless it
+   returns 0.
+
+   Example 24. Set on_sl_reply parameter
+...
+modparam("tm", "on_sl_reply", "stateless_replies")
+...
+
+onreply_route["stateless_replies"] {
+        # do not allow stateless replies to be forwarded
+        return 0;
+}
+
 Functions
 
    Revision History
    Revision $Revision$ $Date$
 
-t_relay_to_udp(ip, port), t_relay_to_tcp(ip, port)
+t_relay_to_udp(ip, port), t_relay_to_udp(), t_relay_to_tcp(ip, port)
+t_relay_to_tcp() t_relay_to_tls(ip, port) t_relay_to_tls()
 
-   Relay a message statefully 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.
+   Relay a message statefully using a fixed protocol either to the
+   specified fixed destination or to a destination derived from the
+   message uri (if the host address and port are not specified). These
+   along with t_relay are the functions 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 19. t_relay_to_udp usage
+   If no parameters are specified the message is sent to a destination
+   derived from the message uri (using sip sepcific DNS lookups), but with
+   the protocol corresponding to the function name.
+
+   Example 25. t_relay_to_udp usage
 ...
-t_relay_to_udp("1.2.3.4", "5060");
+if (src_ip==10.0.0.0/8)
+        t_relay_to_udp("1.2.3.4", "5060"); # sent to 1.2.3.4:5060 over udp
+else
+        t_relay_to_tcp(); # relay to msg. uri, but over tcp
 ...
 
-t_relay()
+t_relay() t_relay(host, port)
 
-   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.
+   Relay a message statefully either to the destination indicated in the
+   current URI (if called without any parameters) or to the specified host
+   and port. In the later case (host and port specified) the protocol used
+   is the same protocol on which the message was received.
 
-   Example 20. t_relay usage
+   t_relay() is the statefull version for forward(uri:host, uri:port)
+   while t_relay(host, port) is similar to forward(host, port).
+
+   In the forward to uri case (t_relay()), if the original URI was
+   rewritten (by UsrLoc, RR, strip/prefix, etc.) the new URI will be
+   taken). The destination (including the protocol) is determined from the
+   uri, using SIP specific DNS resolving if needed (NAPTR, SRV a.s.o
+   depending also on the dns options).
+
+   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 26. t_relay usage
 ...
 if (!t_relay())
 {
@@ -450,7 +630,7 @@ t_on_failure(failure_route)
    Meaning of the parameters is as follows:
      * failure_route - Failure route block to be called.
 
-   Example 21. t_on_failure usage
+   Example 27. t_on_failure usage
 ...
 route {
     t_on_failure("1");
@@ -476,7 +656,7 @@ t_on_reply(onreply_route)
    Meaning of the parameters is as follows:
      * onreply_route - Onreply route block to be called.
 
-   Example 22. t_on_reply usage
+   Example 28. t_on_reply usage
 ...
 loadmodule "/usr/local/lib/ser/modules/nathelper.so"
 ...
@@ -508,7 +688,7 @@ t_on_branch(branch_route)
    Meaning of the parameters is as follows:
      * branch_route - branch route block to be called.
 
-   Example 23. t_on_branch usage
+   Example 29. t_on_branch usage
 ...
 route {
         t_on_branch("1");
@@ -526,7 +706,7 @@ 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 24. append_branch usage
+   Example 30. append_branch usage
 ...
 set_user("john");
 t_fork();
@@ -541,7 +721,7 @@ t_newtran()
    the only way a script can add a new transaction in an atomic way.
    Typically, it is used to deploy a UAS.
 
-   Example 25. t_newtran usage
+   Example 31. t_newtran usage
 ...
 if (t_newtran()) {
     log("UAS logic");
@@ -560,7 +740,7 @@ t_reply(code, reason_phrase)
      * code - Reply code number.
      * reason_phrase - Reason string.
 
-   Example 26. t_reply usage
+   Example 32. t_reply usage
 ...
 t_reply("404", "Not found");
 ...
@@ -573,7 +753,7 @@ t_lookup_request()
    none was found. However this is safely (atomically) done using
    t_newtran.
 
-   Example 27. t_lookup_request usage
+   Example 33. t_lookup_request usage
 ...
 if (t_lookup_request()) {
     ...
@@ -584,7 +764,7 @@ t_retransmit_reply()
 
    Retransmits a reply sent previously by UAS transaction.
 
-   Example 28. t_retransmit_reply usage
+   Example 34. t_retransmit_reply usage
 ...
 t_retransmit_reply();
 ...
@@ -594,7 +774,7 @@ t_release()
    Remove transaction from memory (it will be first put on a wait timer to
    absorb delayed messages).
 
-   Example 29. t_release usage
+   Example 35. t_release usage
 ...
 t_release();
 ...
@@ -607,7 +787,7 @@ t_forward_nonack(ip, port)
      * ip - IP address where the message should be sent.
      * port - Port number.
 
-   Example 30. t_forward_nonack usage
+   Example 36. t_forward_nonack usage
 ...
 t_forward_nonack("1.2.3.4", "5060");
 ...
@@ -619,7 +799,7 @@ t_set_fr(fr_inv_timeout [, fr_timeout])
    invocation, after calling this function. If the transaction is already
    created (e.g called after t_relay() or in an onreply_route) all the
    branches will have their final response timeout updated on-the-fly. If
-   one of the parameters is 0, it's value won't be changed.
+   one of the parameters is 0, its value won't be changed.
 
    Meaning of the parameters is as follows:
      * fr_inv_timeout - new final response timeout (in milliseconds) for
@@ -628,7 +808,9 @@ t_set_fr(fr_inv_timeout [, fr_timeout])
        non-INVITE transaction, or INVITEs which haven't received yet a
        provisional response. See also fr_timer.
 
-   Example 31. t_set_fr usage
+   See also: fr_timer, fr_inv_timer, t_reset_fr().
+
+   Example 37. t_set_fr usage
 ...
 route {
         t_set_fr(10000); # set only fr invite timeout to 10s
@@ -644,6 +826,73 @@ branch_route[1] {
         }
 }
 
+t_reset_fr()
+
+   Resets the fr_inv_timer and fr_timer for the current transaction to the
+   default values (set using the tm module parameters fr_inv_timer and
+   fr_timer).
+
+   It will effectively cancel any previous calls to t_set_fr for the same
+   transaction.
+
+   See also: fr_timer, fr_inv_timer, t_set_fr.
+
+   Example 38. t_reset_fr usage
+...
+route {
+...
+                t_reset_fr();
+...
+}
+
+t_set_max_lifetime(inv_lifetime, noninv_lifetime)
+
+   Sets the maximum lifetime for the current INVITE or non-INVITE
+   transaction, or for transactions created during the same script
+   invocation, after calling this function (that's why it takes values for
+   both INVITE and non-INVITE). If one of the parameters is 0, its value
+   won't be changed.
+
+   It works as a per transaction max_inv_lifetime or max_noninv_lifetime.
+
+   Meaning of the parameters is as follows:
+     * inv_lifetime - maximum INVITE transaction lifetime (in
+       milliseconds). See also max_inv_lifetime.
+       noninv_lifetime - maximum non-INVITE transaction lifetime (in
+       milliseconds). See also max_noninv_lifetime.
+
+   See also: max_inv_lifetime, max_noninv_lifetime, t_reset_max_lifetime.
+
+   Example 39. t_set_max_lifetime usage
+...
+route {
+    if (src_ip=1.2.3.4)
+        t_set_max_lifetime(120000, 0); # set only max_inv_lifetime to 120s
+    else
+        t_set_max_lifetime(90000, 15000); # set the maximum lifetime to 90s if
+                                          # the current transaction is an
+                                          # INVITE and to 15s if not
+}
+
+t_reset_max_lifetime()
+
+   Resets the the maximum lifetime for the current INVITE or non-INVITE
+   transaction to the default value (set using the tm module parameter
+   max_inv_lifetime or max_noninv_lifetime).
+
+   It will effectively cancel any previous calls to t_set_max_lifetime for
+   the same transaction.
+
+   See also: max_inv_lifetime, max_noninv_lifetime, t_set_max_lifetime.
+
+   Example 40. t_reset_max_lifetime usage
+...
+route {
+...
+                t_reset_max_lifetime();
+...
+}
+
 t_set_retr(retr_t1_interval, retr_t2_interval)
 
    Sets the retr_t1_interval and retr_t2_interval for the current
@@ -672,7 +921,9 @@ t_set_retr(retr_t1_interval, retr_t2_interval)
        retr_t2_interval - new T2 (or maximum) retransmission interval (in
        milliseconds). See also retr_t2_timeout.
 
-   Example 32. t_set_retr usage
+   See also: retr_timer1, retr_timer2, t_reset_retr().
+
+   Example 41. t_set_retr usage
 ...
 route {
         t_set_retr(250, 0); # set only T1 to 250 ms
@@ -688,12 +939,48 @@ branch_route[1] {
         }
 }
 
+t_reset_retr()
+
+   Resets the retr_timer1 and retr_timer2 for the current transaction to
+   the default values (set using the tm module parameters retr_timer1 and
+   retr_timer2).
+
+   It will effectively cancel any previous calls to t_set_retr for the
+   same transaction.
+
+   See also: retr_timer1, retr_timer2, t_set_retr.
+
+   Example 42. t_reset_retr usage
+...
+route {
+...
+                t_reset_retr();
+...
+}
+
+t_set_auto_inv_100(0|1)
+
+   Switch automatically sending 100 replies to INVITEs on/off on a per
+   transaction basis. It overrides the auto_inv_100 value for the current
+   transaction.
+
+   See also: auto_inv_100.
+
+   Example 43. t_set_auto_inv_100 usage
+...
+route {
+...
+        if (src_ip==1.2.3.0/24)
+                t_set_auto_inv_100(0); # turn off automatic 100 replies
+...
+}
+
 t_branch_timeout()
 
    Returns true if the failure route is executed for a branch that did
    timeout. It can be used only from the failure_route.
 
-   Example 33. t_branch_timeout usage
+   Example 44. t_branch_timeout usage
 ...
 failure_route[0]{
         if (t_branch_timeout()){
@@ -708,7 +995,7 @@ t_branch_replied()
    receive at least one reply in the past (the "current" reply is not
    taken into account). It can be used only from the failure_route.
 
-   Example 34. t_branch_replied usage
+   Example 45. t_branch_replied usage
 ...
 failure_route[0]{
         if (t_branch_timeout()){
@@ -725,7 +1012,7 @@ t_any_timeout()
    Returns true if at least one of the current transactions branches did
    timeout.
 
-   Example 35. t_any_timeout usage
+   Example 46. t_any_timeout usage
 ...
 failure_route[0]{
         if (!t_branch_timeout()){
@@ -742,7 +1029,7 @@ t_any_replied()
    receive some reply in the past. If called from a failure or onreply
    route, the "current" reply is not taken into account.
 
-   Example 36. t_any_replied usage
+   Example 47. t_any_replied usage
 ...
 onreply_route[0]{
         if (!t_any_replied()){
@@ -756,7 +1043,7 @@ t_grep_status("code")
    Returns true if "code" is the final reply received (or locally
    generated) in at least one of the current transactions branches.
 
-   Example 37. t_grep_status usage
+   Example 48. t_grep_status usage
 ...
 onreply_route[0]{
         if (t_grep_status("486")){
@@ -769,7 +1056,7 @@ t_is_canceled()
 
    Returns true if the current transaction was canceled.
 
-   Example 38. t_is_canceled usage
+   Example 49. t_is_canceled usage
 ...
 failure_route[0]{
         if (t_is_canceled()){
@@ -790,7 +1077,7 @@ t_relay_cancel()
    CANCELs were successfully sent to the pending branches, true if the
    INVITE was not found, and false in case of any error.
 
-   Example 39. t_relay_cancel usage
+   Example 50. t_relay_cancel usage
 if (method == CANCEL) {
         if (!t_relay_cancel()) {  # implicit drop if relaying was successful,
                                   # nothing to do
@@ -803,6 +1090,69 @@ if (method == CANCEL) {
         # do the same as for INVITEs
 }
 
+t_drop_replies()
+
+   Drops all the previously received replies in failure_route block to
+   make sure that none of them is picked up again. Works only if a new
+   branch is added to the transaction, or it is explicitly replied in the
+   script!
+
+   Example 51. t_drop_replies() usage
+...
+failure_route[0]{
+        if (t_check_status("5[0-9][0-9]")){
+                # I do not like the 5xx responses,
+                # so I give another chance to "foobar.com",
+                # and I drop all the replies to make sure that
+                # they are not forwarded to the caller.
+                t_drop_replies();
+
+                rewritehostport("foobar.com");
+                append_branch();
+                t_relay();
+        }
+}
+
+t_save_lumps()
+
+   Forces the modifications of the processed SIP message to be saved in
+   shared memory before t_relay() is called. The new branches which are
+   created in failure_route will contain the same modifications, and any
+   other modification after t_save_lumps() will be lost.
+
+   Note that t_relay() automatically saves the modifications when it is
+   called the first time, there is no need for t_save_lumps() unless
+   message changes between t_save_lumps() and t_relay() must not be
+   propagated to failure_route.
+
+   The transaction must be created by t_newtran() before calling
+   t_save_lumps().
+
+   Example 52. t_save_lumps() usage
+route {
+        ...
+        t_newtran();
+        append_hf("hf1: my first header\r\n");
+        ...
+        t_save_lumps();
+        append_hf("hf2: my second header\r\n");
+        ...
+        t_on_failure("1");
+        t_relay();
+}
+
+failure_route[1] {
+        append_branch();
+        append_hf("hf3: my third header\r\n");
+        #
+        # This branch contains hf1 and hf3, but does
+        # not contain hf2 header.
+        # hf2 would be also present here without
+        # t_save_lumps().
+        ...
+        t_relay();
+}
+
 TM Module API
 
    Revision History

modules/tm/doc/functions.xml

@@ -408,7 +408,7 @@ t_forward_nonack("1.2.3.4", "5060");
 		If the transaction is already created (e.g called after
 		 <function>t_relay()</function> or in an onreply_route) all the
 		 branches will have their final response timeout updated on-the-fly.
-		If one of the parameters is 0, it's value won't be changed.
+		If one of the parameters is 0, its value won't be changed.
 	</para>
 	<para>Meaning of the parameters is as follows:</para>
 	<itemizedlist>
@@ -424,6 +424,12 @@ t_forward_nonack("1.2.3.4", "5060");
 		</para>
 	    </listitem>
 	</itemizedlist>
+	<para>
+		See also: 
+			<varname>fr_timer</varname>,
+			<varname>fr_inv_timer</varname>,
+			<function>t_reset_fr()</function>.
+	</para>
 	<example>
 	    <title><function>t_set_fr</function> usage</title>
 	    <programlisting>
@@ -445,6 +451,121 @@ branch_route[1] {
 	</example>
 	</section>
 
+	<section id="t_reset_fr">
+	<title>
+	    <function>t_reset_fr()</function>
+	</title>
+	<para>
+		Resets the <varname>fr_inv_timer</varname> and 
+		<varname>fr_timer</varname> for the current transaction to the default
+		values (set using the tm module parameters
+		<varname>fr_inv_timer</varname> and <varname>fr_timer</varname>).
+	</para>
+	<para>
+		It will effectively cancel any previous calls to 
+		<function>t_set_fr</function> for the same transaction.
+	</para>
+	<para>
+		See also: <varname>fr_timer</varname>,
+				<varname>fr_inv_timer</varname>,
+				<function>t_set_fr</function>.
+	</para>
+	<example>
+		<title><function>t_reset_fr</function> usage</title>
+		<programlisting>
+...
+route { 
+...
+		t_reset_fr();
+...
+} 
+		</programlisting>
+	</example>
+	</section>
+
+
+	<section id="t_set_max_lifetime">
+	<title>
+	    <function>t_set_max_lifetime(inv_lifetime, noninv_lifetime)</function>
+	</title>
+	<para>
+		Sets the maximum lifetime for the current INVITE or non-INVITE 
+		transaction, or for transactions created during the same script
+		invocation, after calling this function (that's why it takes values
+		for both INVITE and non-INVITE).
+		If one of the parameters is 0, its value won't be changed.
+	</para>
+	<para>
+		It works as a per transaction <varname>max_inv_lifetime</varname> or
+		<varname>max_noninv_lifetime</varname>.
+	</para>
+	<para>Meaning of the parameters is as follows:</para>
+	<itemizedlist>
+	    <listitem>
+		<para><emphasis>inv_lifetime</emphasis> - maximum INVITE transaction
+			lifetime (in milliseconds). See also 
+			<varname>max_inv_lifetime</varname>.
+		</para>
+		<para><emphasis>noninv_lifetime</emphasis> - maximum non-INVITE 
+			transaction lifetime (in milliseconds).
+			See also <varname>max_noninv_lifetime</varname>.
+		</para>
+	    </listitem>
+	</itemizedlist>
+	<para>
+		See also: <varname>max_inv_lifetime</varname>,
+				<varname>max_noninv_lifetime</varname>,
+				<function>t_reset_max_lifetime</function>.
+	</para>
+	<example>
+		<title><function>t_set_max_lifetime</function> usage</title>
+		<programlisting>
+...
+route { 
+    if (src_ip=1.2.3.4)
+        t_set_max_lifetime(120000, 0); # set only max_inv_lifetime to 120s
+    else
+        t_set_max_lifetime(90000, 15000); # set the maximum lifetime to 90s if
+                                          # the current transaction is an 
+                                          # INVITE and to 15s if not
+} 
+
+		</programlisting>
+	</example>
+	</section>
+
+	<section id="t_reset_max_lifetime">
+	<title>
+	    <function>t_reset_max_lifetime()</function>
+	</title>
+	<para>
+		Resets the the maximum lifetime for the current INVITE or non-INVITE 
+		transaction to the default value (set using the tm module parameter
+		<varname>max_inv_lifetime</varname> or 
+		<varname>max_noninv_lifetime</varname>).
+	</para>
+	<para>
+		It will effectively cancel any previous calls to 
+		<function>t_set_max_lifetime</function> for the same transaction.
+	</para>
+	<para>
+		See also: <varname>max_inv_lifetime</varname>,
+				<varname>max_noninv_lifetime</varname>,
+				<function>t_set_max_lifetime</function>.
+	</para>
+	<example>
+		<title><function>t_reset_max_lifetime</function> usage</title>
+		<programlisting>
+...
+route { 
+...
+		t_reset_max_lifetime();
+...
+} 
+		</programlisting>
+	</example>
+	</section>
+
 	<section id="t_set_retr">
 	<title>
 	    <function>t_set_retr(retr_t1_interval, retr_t2_interval)</function>
@@ -487,6 +608,12 @@ branch_route[1] {
 		</para>
 	    </listitem>
 	</itemizedlist>
+	<para>
+		See also: 
+			<varname>retr_timer1</varname>,
+			<varname>retr_timer2</varname>,
+			<function>t_reset_retr()</function>.
+	</para>
 	<example>
 	    <title><function>t_set_retr</function> usage</title>
 	    <programlisting>
@@ -508,6 +635,65 @@ branch_route[1] {
 	</example>
 	</section>
 
+
+	<section id="t_reset_retr">
+	<title>
+	    <function>t_reset_retr()</function>
+	</title>
+	<para>
+		Resets the <varname>retr_timer1</varname> and 
+		<varname>retr_timer2</varname> for the current transaction to the 
+		default values (set using the tm module parameters
+		<varname>retr_timer1</varname> and <varname>retr_timer2</varname>).
+	</para>
+	<para>
+		It will effectively cancel any previous calls to 
+		<function>t_set_retr</function> for the same transaction.
+	</para>
+	<para>
+		See also: <varname>retr_timer1</varname>,
+				<varname>retr_timer2</varname>,
+				<function>t_set_retr</function>.
+	</para>
+	<example>
+		<title><function>t_reset_retr</function> usage</title>
+		<programlisting>
+...
+route { 
+...
+		t_reset_retr();
+...
+} 
+		</programlisting>
+	</example>
+	</section>
+
+	<section id="t_set_auto_inv_100">
+	<title>
+	    <function>t_set_auto_inv_100(0|1)</function>
+	</title>
+	<para>
+		Switch automatically sending 100 replies to INVITEs on/off on a 
+		per transaction basis. It overrides the 
+		<varname>auto_inv_100</varname> value for the current transaction.
+	</para>
+	<para>
+		See also: <varname>auto_inv_100</varname>.
+	</para>
+	<example>
+		<title><function>t_set_auto_inv_100</function> usage</title>
+		<programlisting>
+...
+route { 
+...
+	if (src_ip==1.2.3.0/24)
+		t_set_auto_inv_100(0); # turn off automatic 100 replies
+...
+} 
+		</programlisting>
+	</example>
+	</section>
+
 	<section id="t_branch_timeout">
 	<title>
 	    <function>t_branch_timeout()</function>

modules/tm/doc/params.xml

@@ -21,13 +21,17 @@
 	    negative INVITE reply arrives (in milliseconds).
 	</para>
 	<para>
-	    Default value is 30 seconds.
+	    Default value is 30000 ms (30 seconds).
+	</para>
+	<para>
+		See also: <function>t_set_fr()</function>,
+				<varname>max_noninv_lifetime</varname>.
 	</para>
 	<example>
 	    <title>Set <varname>fr_timer</varname> parameter</title>
 	    <programlisting>
 ...
-modparam("tm", "fr_timer", 10)
+modparam("tm", "fr_timer", 10000)
 ...
 	    </programlisting>
 	</example>
@@ -40,13 +44,125 @@ modparam("tm", "fr_timer", 10)
 	    provisional message was received (in milliseconds).
 	</para>
 	<para>
-	    Default value is 120 seconds.
+	</para>
+		Note: this timer can be restarted when a provisional response is
+		received. For more details see
+		<varname>restart_fr_on_each_reply</varname>.
+	<para>
+	    Default value is 120000 ms (120 seconds).
+	</para>
+	<para>
+		See also: <function>t_set_fr()</function>,
+				<varname>max_inv_lifetime</varname>.
 	</para>
 	<example>
 	    <title>Set <varname>fr_inv_timer</varname> parameter</title>
 	    <programlisting>
 ...
-modparam("tm", "fr_inv_timer", 200)
+modparam("tm", "fr_inv_timer", 180000)
+...
+	    </programlisting>
+	</example>
+    </section>
+
+	<section id="max_inv_lifetime">
+	<title><varname>max_inv_lifetime</varname> (integer)</title>
+	<para>
+		Maximum time an INVITE transaction is allowed to be active (in 
+		milliseconds). After this interval has passed from the transaction
+		creation, the transaction will be either moved into the wait state
+		or in the final response retransmission state, irrespective of the
+		transaction  <varname>fr_inv_timer</varname> and
+		<varname>fr_timer</varname> values.
+	</para>
+	<para>
+		An INVITE transaction will be kept in memory for maximum:
+		<varname>max_inv_lifetime</varname>+<varname>fr_timer</varname>(from 
+		the ack to the final reply wait)+<varname>wt_timer</varname>.
+	</para>
+	<para>
+		The main difference between this timer and 
+		<varname>fr_inv_timer</varname> is that the 
+		<varname>fr_inv_timer</varname> is per branch, while 
+		<varname>max_inv_lifetime</varname> is per the whole transaction.
+		Even on a per branch basis <varname>fr_inv_timer</varname> could be 
+		restarted. For example, by default if 
+		<varname>restart_fr_on_each_reply</varname> is not cleared, the 
+		<varname>fr_inv_timer</varname> will be restarted for each received 
+		provisional reply. Even if <varname>restart_fr_on_each_reply</varname>
+		is not set the <varname>fr_inv_timer</varname> will still be restarted
+		for each increasing reply (e.g. 180, 181, 182, ...). 
+		Another example when a transaction can live substantially more then its
+		<varname>fr_inv_timer</varname> and where
+		<varname>max_inv_lifetime</varname> will help is when dns failover is 
+		used (each failed dns destination can introduce a new branch).
+	</para>
+	<para>
+		The default value is 180000 ms (180 seconds - the rfc3261 
+		timer C value).
+	</para>
+	<para>
+		See also: <varname>max_noninv_lifetime</varname>,
+					<function>t_set_max_lifetime()</function> (allows changing
+					<varname>max_inv_lifetime</varname> on a per transaction
+					basis),
+					<function>t_reset_max_lifetime</function>
+					<varname>fr_timer</varname>,
+					<varname>wt_timer</varname>,
+					<varname>restart_fr_on_each_reply</varname>.
+	</para>
+	<example>
+	    <title>Set <varname>max_inv_lifetime</varname> parameter</title>
+	    <programlisting>
+...
+modparam("tm", "max_inv_lifetime", 150000)
+...
+	    </programlisting>
+	</example>
+    </section>
+
+	<section id="max_noninv_lifetime">
+	<title><varname>max_noninv_lifetime</varname> (integer)</title>
+	<para>
+		Maximum time a non-INVITE transaction is allowed to be active (in 
+		milliseconds). After this interval has passed from the transaction
+		creation, the transaction will be either moved into the wait state
+		or in the final response retransmission state, irrespective of the
+		transaction <varname>fr_timer</varname> value.
+		It's the same as <varname>max_inv_lifetime</varname>, but for 
+		non-INVITEs.
+	</para>
+	<para>
+		A non-INVITE transaction will be kept in memory for maximum:
+		<varname>max_noninv_lifetime</varname>+<varname>wt_timer</varname>.
+	</para>
+	<para>
+		The main difference between this timer and 
+		<varname>fr_timer</varname> is that the 
+		<varname>fr_timer</varname> is per branch, while 
+		<varname>max_noninv_lifetime</varname> is per the whole transaction.
+		An example when a transaction can live substantially more then its
+		<varname>fr_timer</varname> and where
+		<varname>max_noninv_lifetime</varname> will help is when dns failover
+		is used (each failed dns destination can introduce a new branch).
+	</para>
+	<para>
+		The default value is 32000 ms (32 seconds - the rfc3261 timer F value).
+	</para>
+	<para>
+		See also: <varname>max_inv_lifetime</varname>,
+					<function>t_set_max_lifetime()</function> (allows changing
+					<varname>max_noninv_lifetime</varname> on a per transaction
+					basis),
+					<function>t_reset_max_lifetime</function>
+					<varname>fr_timer</varname>,
+					<varname>wt_timer</varname>.
+	</para>
+	<example>
+	    <title>Set <varname>max_noninv_lifetime</varname> parameter</title>
+	    <programlisting>
+...
+modparam("tm", "max_inv_lifetime", 30000)
 ...
 	    </programlisting>
 	</example>
@@ -56,19 +172,20 @@ modparam("tm", "fr_inv_timer", 200)
 	<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,
+	    messages after it completed (in milliseconds); 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.
+	    Default value is 5000 ms (5 seconds).
 	</para>
 	<example>
 	    <title>Set <varname>wt_timer</varname> parameter</title>
 	    <programlisting>
 ...
-modparam("tm", "wt_timer", 10)
+modparam("tm", "wt_timer", 1000)
 ...
 	    </programlisting>
 	</example>
@@ -78,7 +195,11 @@ modparam("tm", "wt_timer", 10)
 	<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.
+	    process will be tried to be deleted again (in milliseconds).
+	</para>
+	<para>
+	    Note: this parameter is obsolete for ser 2.1 (in 2.1 the transaction
+		 is deleted the moment it's not referenced anymore).
 	</para>
 	<para>
 	    Default value is 200 milliseconds.
@@ -87,7 +208,7 @@ modparam("tm", "wt_timer", 10)
 	    <title>Set <varname>delete_timer</varname> parameter</title>
 	    <programlisting>
 ...
-modparam("tm", "delete_timer", 5)
+modparam("tm", "delete_timer", 100)
 ...
 	    </programlisting>
 	</example>
@@ -144,7 +265,7 @@ modparam("tm", "retr_timer2", 2000)
 		 turned it on  for a transaction (like acc does to avoid unaccounted
 		 transactions due to expired timer).
 		Turn this off only if you know the client UACs will timeout and their
-		timeout interval fro INVITEs is lower or equal than tm's
+		timeout interval for INVITEs is lower or equal than tm's
 		<varname>fr_inv_timer</varname>.
 	</para>
 	<para>
@@ -160,6 +281,70 @@ modparam("tm", "noisy_ctimer", 1)
 	</example>
     </section>
 
+	<section id="restart_fr_on_each_reply">
+	<title><varname>restart_fr_on_each_reply</varname> (integer)</title>
+	<para>
+		If set (default), the <varname>fr_inv_timer</varname> for an INVITE
+		transaction will be restarted for each provisional reply received
+		(rfc3261 mandated behaviour). If not set, the 
+		<varname>fr_inv_timer</varname> will be restarted only for the first
+		provisional replies and for increasing replies greater or equal 180
+		(e.g. 180, 181, 182, 185, ...).
+	</para>
+	<para>
+		Setting it to 0 is especially useful when dealing with bad UAs that
+		continuously retransmit 180s, not allowing the transaction to timeout 
+		(and thus making impossible the implementation of certain services,
+		like automatic voicemail after x seconds).
+	</para>
+	<para>
+		Default value is 1 (on).
+	</para>
+	<para>
+		See also: <varname>fr_inv_timer</varname>,
+				<varname>max_inv_lifetime</varname>.
+	</para>
+	<example>
+		<title>Set <varname>restart_fr_on_each_reply</varname>
+				parameter</title>
+		<programlisting>
+...
+modparam("tm", "restart_fr_on_each_reply", 0)
+...
+	    </programlisting>
+	</example>
+	</section>
+
+	<section id="auto_inv_100">
+	<title><varname>auto_inv_100</varname> (integer)</title>
+	<para>
+		If set (default) tm will automatically send and 100 reply to INVITEs.
+	</para>
+	<para>
+		Setting it to 0 one can be used to enable doing first some tests or
+		pre-processing on the INVITE and only if some conditions are met
+		manually send a 100 (using <function>t_reply()</function>). Note 
+		however that in this case all the 100s have to be sent "by hand".
+		<function>t_set_auto_inv_100()</function> might  help to selectively
+		turn off this feature only for some specific transactions.
+	</para>
+	<para>
+		Default value is 1 (on).
+	</para>
+	<para>
+		See also:
+				<function>t_set_auto_inv_100()</function>.
+	</para>
+	<example>
+		<title>Set <varname>auto_inv_100</varname> parameter</title>
+		<programlisting>
+...
+modparam("tm", "auto_inv_100", 0)
+...
+	    </programlisting>
+	</example>
+	</section>
+
 	<section id="unix_tx_timeout">
 	<title><varname>unix_tx_timeout</varname> (integer)</title>
 	<para>
@@ -437,7 +622,7 @@ modparam("tm", "blst_methods_lookup", 1)
 	</para>
 	<para>
 		<emphasis>0</emphasis> will immediately stop the request (INVITE) 
-		retrasmission on the branch and it will behave as if the branch was 
+		retransmission on the branch and it will behave as if the branch was 
 		immediately replied with a 487 (a fake internal 487 reply). The 
 		advantage is the unreplied branches will be terminated immediately.
 		However it introduces a race risk with a possible slightly delayed

modules/tm/doc/tm.xml

@@ -94,22 +94,6 @@
     <section id="tm.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
@@ -137,13 +121,6 @@
 		    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>