
1. TM Module

Jiri Kuthan

   FhG FOKUS

   Copyright © 2003 FhG FOKUS
   Revision History
   Revision $Revision$ $Date$
     _________________________________________________________________

   1.1. Overview
   1.2. Known Issues
   1.3. Parameters

        1.3.1. fr_timer (integer)
        1.3.2. fr_inv_timer (integer)
        1.3.3. max_inv_lifetime (integer)
        1.3.4. max_noninv_lifetime (integer)
        1.3.5. wt_timer (integer)
        1.3.6. delete_timer (integer)
        1.3.7. retr_timer1 (integer)
        1.3.8. retr_timer2 (integer)
        1.3.9. noisy_ctimer (integer)
        1.3.10. restart_fr_on_each_reply (integer)
        1.3.11. auto_inv_100 (integer)
        1.3.12. unix_tx_timeout (integer)
        1.3.13. aggregate_challenges (integer)
        1.3.14. reparse_invite (integer)
        1.3.15. ac_extra_hdrs (string)
        1.3.16. blst_503 (integer)
        1.3.17. blst_503_def_timeout (integer)
        1.3.18. blst_503_min_timeout (integer)
        1.3.19. blst_503_max_timeout (integer)
        1.3.20. blst_methods_add (unsigned integer)
        1.3.21. blst_methods_lookup (unsigned integer)
        1.3.22. cancel_b_method (integer)
        1.3.23. reparse_on_dns_failover (integer)
        1.3.24. on_sl_reply (string)

   1.4. Functions

        1.4.1. 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()
                t_relay_to_sctp(ip, port) t_relay_to_sctp() 

        1.4.2. t_relay() t_relay(host, port) 
        1.4.3. t_on_failure(failure_route) 
        1.4.4. t_on_reply(onreply_route) 
        1.4.5. t_on_branch(branch_route) 
        1.4.6. append_branch() 
        1.4.7. t_newtran() 
        1.4.8. t_reply(code, reason_phrase) 
        1.4.9. t_lookup_request() 
        1.4.10. t_retransmit_reply() 
        1.4.11. t_release() 
        1.4.12. t_forward_nonack() t_forward_nonack(ip, port)
                t_forward_nonack_udp(ip, port) t_forward_nonack_tcp(ip,
                port) t_forward_nonack_tls(ip, port)
                t_forward_nonack_sctp(ip, port) 

        1.4.13. t_set_fr(fr_inv_timeout [, fr_timeout]) 
        1.4.14. t_reset_fr() 
        1.4.15. t_set_max_lifetime(inv_lifetime, noninv_lifetime) 
        1.4.16. t_reset_max_lifetime() 
        1.4.17. t_set_retr(retr_t1_interval, retr_t2_interval) 
        1.4.18. t_reset_retr() 
        1.4.19. t_set_auto_inv_100(0|1) 
        1.4.20. t_branch_timeout() 
        1.4.21. t_branch_replied() 
        1.4.22. t_any_timeout() 
        1.4.23. t_any_replied() 
        1.4.24. t_grep_status("code") 
        1.4.25. t_is_canceled() 
        1.4.26. t_is_expired() 
        1.4.27. t_relay_cancel() 
        1.4.28. t_lookup_cancel(), t_lookup_cancel(1) 
        1.4.29. t_drop_replies() 
        1.4.30. t_save_lumps() 

   1.5. TM Module API

        1.5.1. Defines
        1.5.2. Functions

              1.5.2.1. register_tmcb(cb_type, cb_func) 
              1.5.2.2. load_tm(*import_structure) 
              1.5.2.3. int t_suspend(struct sip_msg *msg, unsigned int
                      *hash_index, unsigned int *label) 

              1.5.2.4. int t_continue(unsigned int hash_index, unsigned
                      int label, struct action *route) 

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
   statefully. 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 unresolvable destination, use stateful mode. Then, only the initial
   message burdens server by DNS queries, subsequent retransmissions 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 these major functions : t_relay,
   t_relay_to_udp and t_relay_to_tcp. All of them setup transaction
   state, absorb retransmissions from upstream, generate downstream
   retransmissions and correlate replies to requests. t_relay forwards to
   current URI (be it original request's URI or a URI changed by some of
   URI-modifying functions, such as sethost). t_relay_to_udp and
   t_relay_to_tcp forward to a specific address over UDP or TCP
   respectively.

   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 statefully 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 program--lot of mutexes, shared memory
   access, malloc and 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
   simplistic 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. Known Issues

     * 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).

1.3. Parameters

   Revision History
   Revision $Revision$ $Date$

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 milliseconds).

   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", 10000)
...

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 milliseconds).

   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", 180000)
...

1.3.3. 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)
...

1.3.4. 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)
...

1.3.5. wt_timer (integer)

   Time for which a transaction stays in memory to absorb delayed
   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).

   Default value is 5000 ms (5 seconds).

   Example 5. Set wt_timer parameter
...
modparam("tm", "wt_timer", 1000)
...

1.3.6. delete_timer (integer)

   Time after which a to-be-deleted transaction currently ref-ed by a
   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 6. Set delete_timer parameter
...
modparam("tm", "delete_timer", 100)
...

1.3.7. retr_timer1 (integer)

   Initial retransmission period (in milliseconds).

   Default value is 500 milliseconds.

   Example 7. Set retr_timer1 parameter
...
modparam("tm", "retr_timer1", 1000)
...

1.3.8. retr_timer2 (integer)

   Maximum retransmission period (in milliseconds). The retransmission
   interval starts with retr_timer1 and increases until it reaches this
   value. After this it stays constant at retr_timer2.

   Default value is 4000 milliseconds.

   Example 8. Set retr_timer2 parameter
...
modparam("tm", "retr_timer2", 2000)
...

1.3.9. noisy_ctimer (integer)

   If set, INVITE transactions that time-out (FR INV timer) will be
   always replied. If it's not set, the transaction has only one branch
   and no response was ever received on this branch, it will be silently
   dropped (no 408 reply will be generated) This behavior is overridden
   if a request is forked, the transaction has a failure route or
   callback, or 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 for INVITEs is lower or equal than
   tm's fr_inv_timer.

   Default value is 1 (on).

   Example 9. Set noisy_ctimer parameter
...
modparam("tm", "noisy_ctimer", 1)
...

1.3.10. 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)
...

1.3.11. 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)
...

1.3.12. unix_tx_timeout (integer)

   Unix socket transmission timeout, in milliseconds.

   If unix sockets are used (e.g.: to communicate with sems) and sending
   a message on a unix socket takes longer then unix_tx_timeout, the send
   will fail.

   The default value is 500 milliseconds.

   Example 12. Set unix_tx_timeout parameter
...
modparam("tm", "unix_tx_timeout", 250)
...

1.3.13. aggregate_challenges (integer)

   If set (default), the final reply is a 401 or a 407 and more then one
   branch received a 401 or 407, then all the WWW-Authenticate and
   Proxy-Authenticate headers from all the 401 and 407 replies will be
   aggregated in a new final reply. If only one branch received the
   winning 401 or 407 then this reply will be forwarded (no new one will
   be built). If 0 only the first 401, or if no 401 was received the
   first 407, will be forwarded (no header aggregation).

   Default value is 1 (required by rfc3261).

   Example 13. Set aggregate_challenges parameter
...
modparam("tm", "aggregate_challenges", 0)
...

1.3.14. reparse_invite (integer)

   If set (default), the CANCEL and negative ACK requests are constructed
   from the INVITE message which was sent out instead of building them
   from the received request. The disadvantage is that the outgoing
   INVITE has to be partially re-parsed, the advantage is that the
   CANCEL/ACK is always RFC 3261-compliant, it always contains the same
   route-set as the INVITE message. Do not disable the INVITE re-parsing
   for example in the following cases:

   - The INVITE contains a preloaded route-set, and SER forwards the
   message to the next hop according to the Route header. The Route
   header is not removed in the CANCEL without reparse_invite=1.

   - SER record-routes, thus an in-dialog INVITE contains a Route header
   which is removed during loose routing. If the in-dialog INVITE is
   rejected, the negative ACK still contains the Route header without
   reparse_invite=1.

   Default value is 1.

   Example 14. Set reparse_invite parameter
...
modparam("tm", "reparse_invite", 0)
...

1.3.15. ac_extra_hdrs (string)

   Header fields prefixed by this parameter value are included in the
   CANCEL and negative ACK messages if they were present in the outgoing
   INVITE.

   Note, that the parameter value effects only those headers which are
   not covered by RFC-3261 (which are neither mandatory nor prohibited in
   CANCEL and ACK), and the parameter can be used only together with
   reparse_invite=1.

   Default value is "".

   Example 15. Set ac_extra_hdrs parameter
...
modparam("tm", "ac_extra_hdrs", "myfavoriteheaders-")
...

1.3.16. blst_503 (integer)

   If set and the blacklist support is enabled, every 503 reply source is
   added to the blacklist. The initial blacklist timeout (or ttl) depends
   on the presence of a Retry-After header in the reply and the values of
   the following tm parameters: blst_503_def_timeout,
   blst_503_min_timeout and blst_503_max_timeout.

   WARNING:blindly allowing 503 blacklisting could be very easily
   exploited for DOS attacks in most network setups.

   The default value is 0 (disabled due to the reasons above).

   Example 16. Set blst_503 parameter
...
modparam("tm", "blst_503", 1)
...

1.3.17. blst_503_def_timeout (integer)

   Blacklist interval in seconds for a 503 reply with no Retry-After
   header. See also blst_503, blst_503_min_timeout and
   blst_503_max_timeout.

   The default value is 0, which means that if no Retry-After header is
   present, the 503 reply source will not be blacklisted (rfc conformant
   behaviour).

   Example 17. Set blst_503_def_timeout parameter
...
modparam("tm", "blst_503_def_timeout", 120)
...

1.3.18. blst_503_min_timeout (integer)

   Minimum blacklist interval in seconds for a 503 reply with a
   Retry-After header. It will be used if the Retry-After value is
   smaller. See also blst_503, blst_503_def_timeout and
   blst_503_max_timeout.

   The default value is 0

   Example 18. Set blst_503_min_timeout parameter
...
modparam("tm", "blst_503_min_timeout", 30)
...

1.3.19. blst_503_max_timeout (integer)

   Maximum blacklist interval in seconds for a 503 reply with a
   Retry-After header. It will be used if the Retry-After value is
   greater. See also blst_503, blst_503_def_timeout and
   blst_503_min_timeout.

   The default value is 3600

   Example 19. Set blst_503_max_timeout parameter
...
modparam("tm", "blst_503_max_timeout", 604800)
...

1.3.20. blst_methods_add (unsigned integer)

   Bitmap of method types that trigger blacklisting on transaction
   timeouts. (This setting has no effect on blacklisting because of send
   failures.)

   The following values are associated to the request methods: INVITE=1,
   CANCEL=2, ACK=4 (not retransmitted, thus, never times-out), BYE=8,
   INFO=16, REGISTER=32, SUBSCRIBE=64, NOTIFY=126, OTHER=256 (all the
   unknown types). Check parser/msg_parser.h for farther details.

   Change the value carefully, because requests not having provisional
   response (everything but INVITE) can easily cause the next hop to be
   inserted into the blacklist by mistake. For exmaple the next hop is a
   proxy, it is alive, but waiting for the response of the UAS, and has
   higher fr_timer value.

   The default value is 1, only INVITEs trigger blacklisting

   Example 20. Set blst_methods_add parameter
...
# INVITEs and REGISTERs trigger blacklisting
modparam("tm", "blst_methods_add", 33)
...

1.3.21. blst_methods_lookup (unsigned integer)

   Bitmap of method types that are looked-up in the blacklist before
   statefull forwarding. See also blst_methods_add

   The default value is 4294967287, every method type except BYE. (We try
   to deliver BYEs no matter what)

   Example 21. Set blst_methods_lookup parameter
...
# lookup only INVITEs
modparam("tm", "blst_methods_lookup", 1)
...

1.3.22. cancel_b_method (integer)

   Method used when attempting to CANCEL an unreplied transaction branch
   (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) 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 2xx reply. In this case we could
   have an UA receiving a 2xx after a 487. Moreover this risk is greatly
   amplified by packet loss (e.g. if an 180 is lost the branch will look
   as unreplied and a CANCEL will silently drop the branch, but a 2xx can
   still come at a later time). This is the behaviour for ser versions
   older then 2.1.

   1 will keep retransmitting the request on unreplied branches. If a
   provisional answer is later received a CANCEL will be immediately sent
   back (attempting to quickly trigger a 487). This approach is race free
   and avoids the 2xx after 487 problem, but it's more resource
   intensive: faced with a branch towards and UA that doesn't answer, a
   CANCEL attempt will keep the transaction alive for the whole timeout
   interval (fr_timer).

   2 will send and retransmit CANCEL even on unreplied branches, stopping
   the request retransmissions. This has the same advantages as 1 and
   also avoids the extra roundtrip in the case of the provisional reply,
   but it's not RFC 3261 conforming (the RFC allows sending CANCELs only
   on pending branches).

   The default value is 1.

   Example 22. Set cancel_b_method parameter
...
modparam("tm", "cancel_b_method", 1)
...

1.3.23. 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)
...

1.3.24. 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;
}

1.4. Functions

   Revision History
   Revision $Revision$ $Date$

1.4.1.  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()
t_relay_to_sctp(ip, port) t_relay_to_sctp()

   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.

   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
...
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
...

1.4.2.  t_relay() t_relay(host, port)

   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.

   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())
{
    sl_reply_error();
    break;
};
...

1.4.3.  t_on_failure(failure_route)

   Sets failure routing block, to which control is passed after a
   transaction completed with a negative result but before sending a
   final reply. In the referred block, you can either start a new branch
   (good for services such as forward_on_no_reply) or send a final reply
   on your own (good for example for message silo, which received a
   negative reply from upstream and wants to tell upstream "202 I will
   take care of it"). Note that the set of commands which are usable
   within failure_routes is strictly limited to rewriting URI, initiating
   new branches, logging, and sending stateful replies (t_reply). Any
   other commands may result in unpredictable behavior and possible
   server failure. Note that whenever failure_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:
     * failure_route - Failure route block to be called.

   Example 27. t_on_failure usage
...
route {
    t_on_failure("1");
    t_relay();
}

failure_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.  t_on_reply(onreply_route)

   Sets the reply routing block, to which control is passed when a reply
   for the current transaction is received. Note that the set of commands
   which are usable within onreply_routes is limited.

   Meaning of the parameters is as follows:
     * onreply_route - Onreply route block to be called.

   Example 28. t_on_reply usage
...
loadmodule "/usr/local/lib/ser/modules/nathelper.so"
...
route {
        /* if natted */
        t_on_reply("1");
        t_relay();
}

onreply_route[1] {
        if (status=~ "(183)|2[0-9][0-9]"){
                force_rtp_proxy();
                search_append('^(Contact|m)[ \t]*:.*sip:[^>[:cntrl:]]*', ';nat=
yes');
        }
        if (nat_uac_test("1")){
                fix_nated_contact();
        }
}

1.4.5.  t_on_branch(branch_route)

   Sets the branch routing block, to which control is passed after
   forking (when a new branch is created). For now branch routes are
   intended only for last minute changes of the SIP messages (like adding
   new headers). Note that the set of commands which are usable within
   branch_routes is very limited. It is not possible to drop a message or
   generate a reply.

   Meaning of the parameters is as follows:
     * branch_route - branch route block to be called.

   Example 29. t_on_branch usage
...
route {
        t_on_branch("1");
        t_relay();
}

branch_route[1] {
        if (uri=~"sip:[0-9]+"){
                append_hf("P-Warn: numeric uri\r\n");
        }
}

1.4.6.  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 30. append_branch usage
...
set_user("john");
t_fork();
set_user("alice");
t_fork();
t_relay();
...

1.4.7.  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 31. 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.8.  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 32. t_reply usage
...
t_reply("404", "Not found");
...

1.4.9.  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
   typical 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 33. t_lookup_request usage
...
if (t_lookup_request()) {
    ...
};
...

1.4.10.  t_retransmit_reply()

   Retransmits a reply sent previously by UAS transaction.

   Example 34. t_retransmit_reply usage
...
t_retransmit_reply();
...

1.4.11.  t_release()

   Remove transaction from memory (it will be first put on a wait timer
   to absorb delayed messages).

   Example 35. t_release usage
...
t_release();
...

1.4.12.  t_forward_nonack() t_forward_nonack(ip, port)
t_forward_nonack_udp(ip, port) t_forward_nonack_tcp(ip, port)
t_forward_nonack_tls(ip, port) t_forward_nonack_sctp(ip, port)

   mainly for internal usage--forward a non-ACK request statefully.

   Meaning of the parameters is as follows:
     * ip - IP address where the message should be sent.
     * port - Port number.

   Example 36. t_forward_nonack usage
...
t_forward_nonack("1.2.3.4", "5060");
...

1.4.13.  t_set_fr(fr_inv_timeout [, fr_timeout])

   Sets the fr_inv_timeout and optionally fr_timeout for the current
   transaction or for transactions created during the same script
   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, its value won't be changed.

   Meaning of the parameters is as follows:
     * fr_inv_timeout - new final response timeout (in milliseconds) for
       INVITEs. See also fr_inv_timer.
       fr_timeout - new final response timeout (in milliseconds) for
       non-INVITE transaction, or INVITEs which haven't received yet a
       provisional response. See also fr_timer.

   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
        t_on_branch("1");
        t_relay();
}

branch_route[1] {
        # if we are calling the pstn, extend the invite timeout to 50s
        # for all the branches, and set the no-reply-received timeout to 2s
        if (uri=~"sip:[0-9]+"){
                t_set_fr(50000, 2000);
        }
}

1.4.14.  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();
...
}

1.4.15.  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
}

1.4.16.  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();
...
}

1.4.17.  t_set_retr(retr_t1_interval, retr_t2_interval)

   Sets the retr_t1_interval and retr_t2_interval for the current
   transaction or for transactions created during the same script
   invocation, after calling this function. If one of the parameters is
   0, it's value won't be changed. If the transaction is already created
   (e.g called after t_relay() or in an onreply_route) all the existing
   branches will have their retransmissions intervals updated on-the-fly:
   if the retransmission interval for the branch has not yet reached T2
   the interval will be reset to retr_t1_interval, else to
   retr_t2_interval. Note that the change will happen after the current
   interval expires (after the next retransmission, the next-next
   retransmission will take place at retr_t1_interval or
   retr_t2_interval). All new branches of the same transaction will start
   with the new values. This function will work even if it's called in
   the script before a transaction creating function (e.g.:
   t_set_retr(500, 4000); t_relay()). All new transaction created after
   this function call, during the same script invocation will use the new
   values. Note that this function will work only if tm is compile with
   -DTM_DIFF_RT_TIMEOUT (which increases every transaction size with 4
   bytes).

   Meaning of the parameters is as follows:
     * retr_t1_interval - new T1 retransmission interval (in
       milliseconds). See also retr_t1_timeout.
       retr_t2_interval - new T2 (or maximum) retransmission interval (in
       milliseconds). See also retr_t2_timeout.

   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
        t_on_branch("1");
        t_relay();
}

branch_route[1] {
        # if we are calling the a remote pstn, extend T1 and decrease T2
        # for all the branches
        if (uri=~"sip:[0-9]+"){
                t_set_retr(500, 2000);
        }
}

1.4.18.  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();
...
}

1.4.19.  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
...
}

1.4.20.  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 44. t_branch_timeout usage
...
failure_route[0]{
        if (t_branch_timeout()){
                log("timeout\n");
                # ...
        }
}

1.4.21.  t_branch_replied()

   Returns true if the failure route is executed for a branch that did
   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 45. t_branch_replied usage
...
failure_route[0]{
        if (t_branch_timeout()){
                if (t_branch_replied())
                        log("timeout after receiving a reply (no answer?)\n");
                else
                        log("timeout, remote side seems to be down\n");
                # ...
        }
}

1.4.22.  t_any_timeout()

   Returns true if at least one of the current transactions branches did
   timeout.

   Example 46. t_any_timeout usage
...
failure_route[0]{
        if (!t_branch_timeout()){
                if (t_any_timeout()){
                        log("one branch did timeout\n");
                        sl_send_reply("408", "Timeout");
                }
        }
}

1.4.23.  t_any_replied()

   Returns true if at least one of the current transactions branches did
   receive some reply in the past. If called from a failure or onreply
   route, the "current" reply is not taken into account.

   Example 47. t_any_replied usage
...
onreply_route[0]{
        if (!t_any_replied()){
                log("first reply received\n");
                # ...
        }
}

1.4.24.  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 48. t_grep_status usage
...
onreply_route[0]{
        if (t_grep_status("486")){
                /* force a 486 reply, even if this is not the winning branch */
                t_reply("486", "Busy");
        }
}

1.4.25.  t_is_canceled()

   Returns true if the current transaction was canceled.

   Example 49. t_is_canceled usage
...
failure_route[0]{
        if (t_is_canceled()){
                log("transaction canceled\n");
                # ...
        }
}

1.4.26.  t_is_expired()

   Returns true if the current transaction has already been expired, i.e.
   the max_inv_lifetime/max_noninv_lifetime interval has already elapsed.

   Example 50. t_is_expired usage
...
failure_route[0]{
        if (t_is_expired()){
                log("transaction expired\n");
                # There is no point in adding a new branch.
        }
}

1.4.27.  t_relay_cancel()

   Forwards the CANCEL if the corresponding INVITE transaction exists.
   The function is supposed to be used at the very beginning of the
   script, because the CANCELs can be caught and the rest of the script
   can be bypassed this way. Do not disable reparse_invite module
   parameter, and call t_relay_cancel() right after the sanity tests.

   Return value is 0 (drop) if the corresponding INVITE was found and the
   CANCELs were successfully sent to the pending branches, true if the
   INVITE was not found, and false in case of any error.

   Example 51. t_relay_cancel usage
if (method == CANCEL) {
        if (!t_relay_cancel()) {  # implicit drop if relaying was successful,
                                  # nothing to do

                # corresponding INVITE transaction found but error occurred
                sl_reply("500", "Internal Server Error");
                drop;
        }
        # bad luck, corresponding INVITE transaction is missing,
        # do the same as for INVITEs
}

1.4.28.  t_lookup_cancel(), t_lookup_cancel(1)

   Returns true if the corresponding INVITE transaction exists for a
   CANCEL request. The function can be called at the beginning of the
   script to check whether or not the CANCEL can be immediately forwarded
   bypassing the rest of the script. Note however that t_relay_cancel
   includes t_lookup_cancel as well, therefore it is not needed to
   explicitly call this function unless something has to be logged for
   example.

   If the function parameter (optional) is set to 1, the message flags
   are overwritten with the flags of the INVITE. isflagset() can be used
   to check the flags of the previously forwarded INVITE in this case.

   Example 52. t_lookup_cancel usage
if (method == CANCEL) {
        if (t_lookup_cancel()) {
                log("INVITE transaction exists");
                if (!t_relay_cancel()) {  # implicit drop if
                                          # relaying was successful,
                                          # nothing to do

                        # corresponding INVITE transaction found
                        # but error occurred
                        sl_reply("500", "Internal Server Error");
                        drop;
                }
        }
        # bad luck, corresponding INVITE transaction is missing,
        # do the same as for INVITEs
}

1.4.29.  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 53. 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();
        }
}

1.4.30.  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 54. 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();
}

1.5. TM Module API

   Revision History
   Revision $Revision$ $Date$

   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
 <dst uri>\n
 <CR_separated_headers>\n
 <body>\n
 .\n
 \n

   (Filename is to where a report will be dumped. ser assumes /tmp as
   file's directory.)

   Note 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
sip:sender@iptel.org
sip:mrx@iptel.org
header:value
foo:bar
bznk:hjhjk
p_header: p_value

body body body
yet body
end of body
.

   or cat test/transaction.fifo > /tmp/ser_fifo

1.5.1. Defines

     * ACK_TAG enables stricter matching of acknowledgments 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
       constitute 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.

1.5.2. Functions

1.5.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.

1.5.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.

1.5.2.3.  int t_suspend(struct sip_msg *msg, unsigned int *hash_index,
unsigned int *label)

   For programmatic use only. This function together with t_continue()
   can be used to implement asynchronous actions: t_suspend() saves the
   transaction, returns its identifiers, and t_continue() continues the
   SIP request processing. (The request processing does not continue from
   the same point in the script, a separate route block defined by the
   parameter of t_continue() is executed instead. The reply lock is held
   during the route block execution.) FR timer is ticking while the
   transaction is suspended, and the transaction's failure route is
   executed if t_continue() is not called in time.

   Missing: message lumps are saved by t_suspend() and are not updated by
   the subsequent t_relay(). This means that the modifications made
   between them are lost.

   Meaning of the parameters is as follows:
     * msg - SIP message pointer.
     * hash_index - transaction identifier.
     * label - transaction identifier.

   Return value: 0 - success, <0 - error.

   Usage: Allocate a memory block for storing the transaction identifiers
   (hash_index and label), and for storing also any variable related to
   the async query. Before calling t_suspend(), register for the
   following callbacks, and pass the pointer to the allocated shared
   memory as a parameter: TMCB_ON_FAILURE, TMCB_DESTROY, and
   TMCB_E2ECANCEL_IN (in case of INVITE transaction). The async operation
   can be cancelled, if it is still pending, when TMCB_ON_FAILURE or
   TMCB_E2ECANCEL_IN is called. TMCB_DESTROY is suitable to free the
   shared memory allocated for the async and SIP transaction identifiers.
   Once the async query result is available call t_continue(), see below.
   The SIP transaction must exist before calling t_suspend(), and the
   module function calling t_suspend() should return 0 to make sure that
   the script processing does not continue.

1.5.2.4.  int t_continue(unsigned int hash_index, unsigned int label, struct
action *route)

   For programmatic use only. This function is the pair of t_suspend(),
   and is supposed to be called when the asynchronous query result is
   available. The function executes a route block with the saved SIP
   message. It is possible to add more branches to the transaction, or
   send a reply from the route block.

   Meaning of the parameters is as follows:
     * hash_index - transaction identifier.
     * label - transaction identifier.
     * route - route block to execute.

   Return value: 0 - success, <0 - error.
