kamailio/modules/tm

1. TM Module

Jiri Kuthan

FhG FOKUS

Juha Heinanen



Copyright � 2003 FhG FOKUS

Copyright � 2008 Juha Heinanen
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. auto_inv_100_reason (string)
1.3.13. unix_tx_timeout (integer)
1.3.14. aggregate_challenges (integer)
1.3.15. reparse_invite (integer)
1.3.16. ac_extra_hdrs (string)
1.3.17. blst_503 (integer)
1.3.18. blst_503_def_timeout (integer)
1.3.19. blst_503_min_timeout (integer)
1.3.20. blst_503_max_timeout (integer)
1.3.21. blst_methods_add (unsigned integer)
1.3.22. blst_methods_lookup (unsigned integer)
1.3.23. cancel_b_method (integer)
1.3.24. reparse_on_dns_failover (integer)
1.3.25. on_sl_reply (string)
1.3.26. fr_inv_timer_next (integer)
1.3.27. contacts_avp (string)
1.3.28. fr_timer_avp (string)
1.3.29. fr_inv_timer_avp (string)
1.3.30. unmatched_cancel (string)
1.3.31. ruri_matching (integer)
1.3.32. via1_matching (integer)
1.3.33. pass_provisional_replies (integer)
1.3.34. default_code (integer)
1.3.35. default_reason (string)
1.3.36. disable_6xx_block (integer)

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.4.31. t_load_contacts()
1.4.32. t_next_contacts()
1.4.33. t_check_trans()
1.4.34. t_set_disable_6xx(0|1)
1.4.35. t_set_disable_failover(0|1)

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.

Note

Several Kamailio (OpenSER) TM module functionalities are now
implemented in the TMX module: "modules_k/tmx". Check it to see if what
you are looking for is there.

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() auto_inv_100_reason.

Example 11. Set auto_inv_100 parameter
...
modparam("tm", "auto_inv_100", 0)
...

1.3.12. auto_inv_100_reason (string)

Set reason text of the automatically send 100 to an INVITE.

Default value is "trying -- your call is important to us".

See also: auto_inv_100.

Example 12. Set auto_inv_100_reason parameter
...
modparam("tm", "auto_inv_100_reason", "Trying")
...

1.3.13. 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 13. Set unix_tx_timeout parameter
...
modparam("tm", "unix_tx_timeout", 250)
...

1.3.14. 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 14. Set aggregate_challenges parameter
...
modparam("tm", "aggregate_challenges", 0)
...

1.3.15. 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 15. Set reparse_invite parameter
...
modparam("tm", "reparse_invite", 0)
...

1.3.16. 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 16. Set ac_extra_hdrs parameter
...
modparam("tm", "ac_extra_hdrs", "myfavoriteheaders-")
...

1.3.17. 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 17. Set blst_503 parameter
...
modparam("tm", "blst_503", 1)
...

1.3.18. 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 18. Set blst_503_def_timeout parameter
...
modparam("tm", "blst_503_def_timeout", 120)
...

1.3.19. 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 19. Set blst_503_min_timeout parameter
...
modparam("tm", "blst_503_min_timeout", 30)
...

1.3.20. 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 20. Set blst_503_max_timeout parameter
...
modparam("tm", "blst_503_max_timeout", 604800)
...

1.3.21. 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 21. Set blst_methods_add parameter
...
# INVITEs and REGISTERs trigger blacklisting
modparam("tm", "blst_methods_add", 33)
...

1.3.22. 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 22. Set blst_methods_lookup parameter
...
# lookup only INVITEs
modparam("tm", "blst_methods_lookup", 1)
...

1.3.23. 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 23. Set cancel_b_method parameter
...
modparam("tm", "cancel_b_method", 1)
...

1.3.24. 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 24. Set reparse_on_dns_failover parameter
...
modparam("tm", "reparse_on_dns_failover", 0)
...

1.3.25. 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 25. 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.3.26. fr_inv_timer_next (integer)

Value of the Final Response timeout for INVITE transactions to be used
during serial forwarding:

Function t_next_contacts() sets fr_inv_timer to fr_inv_timer_next value
if, after t_next_contacts() is called, there are still lower qvalue
contacts available, and to fr_inv_timer value if there are not.

Default value is 30.

Example 26. Set fr_inv_timer_next parameter
...
modparam("tm", "fr_inv_timer_next", 10)
...

1.3.27. contacts_avp (string)

Internal AVP that t_load_contacts() function uses to store contacts of
the destination set and that t_next_contacts() function uses to restore
those contacts.

Default value is "NULL" (t_load_contacts()/t_next_contacts() functions
are disabled).

Example 27. Set contacts_avp parameter
...
modparam("tm", "contacts_avp", "$avp(i:25)")
...

1.3.28. fr_timer_avp (string)

The value of fr_timer timer can be overriden on per-transaction basis.
The administrator can provide a value to be used for a particular
transaction in an AVP. This parameter contains the name of the AVP that
will be checked. If the AVP exists then its value will be used for the
fr_timer timer, effectively overriding the value configured in fr_timer
parameter for the current transaction.

The value of this parameter is the the name of the AVP to be checked,
without the $ character or "$avp" prefix.

Note

The value of the AVP is expected to be expressed in seconds and not
milliseconds (unlike the rest of the timers).

This parameter is kept for backwards compatibility (hence its value
expressed in seconds instead of milliseconds and its arcane way of
specifying the avps). The recommended replacement is using t_set_fr()
on a per transaction basis.

See also: t_set_fr(), fr_timer.

Example 28. Set fr_timer_avp parameter
...
modparam("tm", "fr_timer_avp", "i:708")
...

1.3.29. fr_inv_timer_avp (string)

The value of fr_inv_timer timer can be overriden on per-transaction
basis. The administrator can provide a value to be used for a
particular transaction in an AVP. This parameter contains the name of
the AVP that will be checked. If the AVP exists, is non-empty and
non-zero then its value will be used for the fr_inv_timer timer,
effectively overriding the value configured in fr_inv_timer parameter
for the current transaction.

The value of this parameter is the the name of the AVP to be checked,
without the $ character or "$avp" prefix.

Note

The value of the AVP is expected to be expressed in seconds and not
milliseconds (unlike the rest of the timers).

This parameter is kept for backwards compatibility (hence its value
expressed in seconds instead of milliseconds and its arcane way of
specifying the avps). The recommended replacement is using t_set_fr()
on a per transaction basis.

See also: t_set_fr(), fr_inv_timer.

Example 29. Set fr_inv_timer_avp parameter
...
modparam("tm", "fr_inv_timer_avp", "my_fr_inv_timer")
...

1.3.30. unmatched_cancel (string)

This parameter selects between forwarding CANCELs that do not match any
transaction statefully (0, default value), statelessly (1) or dropping
them (2). Note that the statefull forwarding has an additional hidden
advantage: tm will be able to recognize INVITEs that arrive after their
CANCEL. Note also that this feature could be used to try a memory
exhaustion DOS attack against a proxy that authenticates all requests,
by continuously flooding the victim with CANCELs to random destinations
(since the CANCEL cannot be authenticated, each received bogus CANCEL
will create a new transaction that will live by default 30s).

Default value is 0.

Example 30. Set unmatched_cancel parameter
...
modparam("tm", "unmatched_cancel", "2")
...

1.3.31. ruri_matching (integer)

If set it will also try to match the request uri when doing pre-3261
transaction matching (the via branch parameter does not contain the
3261 cookie).

The only reason to have it not set is for interoperability with old,
broken implementations.

Default value is 1 (on).

Can be set at runtime, e.g.:
$ sercmd cfg.set_now_int tm ruri_matching 0

Example 31. Set ruri_matching parameter
...
modparam("tm", "ruri_matching", 1)
...

1.3.32. via1_matching (integer)

If set it will also try to match the topmost via when doing pre-3261
transaction matching (the via branch parameter does not contain the
3261 cookie).

The only reason to have it not set is for interoperability with old,
broken implementations.

Default value is 1 (on).

Can be set at runtime, e.g.:
$ sercmd cfg.set_now_int tm via1_matching 0

Example 32. Set via1_matching parameter
...
modparam("tm", "via1_matching", 1)
...

1.3.33. pass_provisional_replies (integer)

If set, TMCB_LOCAL_REPONSE_OUT tm registered callbacks will be called
also for provisional replies.

Default value is 0 (off).

Can be set at runtime, e.g.:
$ sercmd cfg.set_now_int tm pass_provisional_replies 1

Example 33. Set pass_provisional_replies parameter
...
modparam("tm", "pass_provisional_replies", 1)
...

1.3.34. default_code (integer)

Default response code sent by t_reply() if it cannot retrieve its
parameters (e.g. inexistent avp). Valid values are between 400 and 699.

Default value is 500.

Can be set at runtime, e.g.:
$ sercmd cfg.set_now_int tm default_code 505

Example 34. Set default_code parameter
...
modparam("tm", "default_code", 501)
...

1.3.35. default_reason (string)

Default SIP reason phrase sent by t_reply() if it cannot retrieve its
parameters (e.g. inexistent avp).

Default value is "Server Internal Error".

Can be set at runtime, e.g.:
$ sercmd cfg.set_now_string tm default_reason "Unknown error"

Example 35. Set default_reason parameter
...
modparam("tm", "default_reason", "Unknown reason")
...

1.3.36. disable_6xx_block (integer)

If set tm will treat all the 6xx replies like normal replies (warning:
this would be non-rfc conformant behaviour).

If not set (default) receiving a 6xx will cancel all the running
parallel branches, will stop dns failover and forking. However serial
forking using append_branch() in the failure_route will still work.

It can be overwritten on a per transaction basis using
t_set_disable_6xx().

Default value is 0 (off, rfc conformant behaviour).

Can be set at runtime, e.g.:
$ sercmd cfg.set_now_int tm disable_6xx_block 0

See also: t_set_disable_6xx().

Example 36. Set disable_6xx_block parameter
...
modparam("tm", "disable_6xx_block", 1)
...

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 37. 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 38. 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 39. 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 40. 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=y
es');
}
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 41. 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 42. 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 43. 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 44. 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 look-up is to introduce a new transaction if
none was found. However this is safely (atomically) done using
t_newtran.

Example 45. t_lookup_request usage
...
if (t_lookup_request()) {
...
};
...

1.4.10. t_retransmit_reply()

Retransmits a reply sent previously by UAS transaction.

Example 46. 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 47. 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 48. 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 49. 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 50. 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 51. 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 52. 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 53. 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 54. 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 55. 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 56. 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 57. 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 58. 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 59. 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 60. 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 61. 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 62. 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 63. 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 64. 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 65. 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 66. 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.4.31. t_load_contacts()

Loads contacts in destination set in increasing qvalue order as values
of contacts_avp. If all contacts in the destination set have the same
qvalue, t_load_contacts() does not do anything thus minimizing
performance impact of serial forking capability when it is not needed.
Returns 1 if loading of contacts succeeded or there was nothing to do.
Returns -1 on error (see syslog).

This function can be used from REQUEST_ROUTE.

Example 67. t_load_contacts usage
...
if (!t_load_contacts()) {
sl_send_reply("500", "Server Internal Error - Cannot load contacts");
exit;
};
...

1.4.32. t_next_contacts()

If transaction does not exist when t_next_contacts() is called,
replaces Request-URI with the first contacts_avp value, adds the
remaining contacts_avp values with the same qvalue as branches, and
destroys those AVPs. It does nothing if there are no contacts_avp
values. Returns 1 if there were no errors and -1 if an error occurred
(see syslog).

If transaction does exist when t_next_contacts() is called, adds the
first contacts_avp value and all following contacts_avp values with the
same qvalue as new branches to request and destroys those AVPs. Returns
1 if new branches were successfully added and -1 on error (see syslog)
or if there were no more contacts_avp values.

This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

Example 68. t_next_contacts usage
...
# First call after t_load_contacts() when transaction does not exist yet
# and contacts should be available
if (!t_next_contacts()) {
sl_send_reply("500", "Server Internal Error - Cannot get contacts");
} else {
t_relay();
};
...
# Following call, when transaction exists and there may or may not be
# contacts left
if (!t_next_contacts()) {
t_reply("408", "Request Timeout");
} else {
t_relay();
};
...

1.4.33. t_check_trans()

t_check_trans() can be used to quickly check if a message belongs or is
related to a transaction. It behaves differently for different types of
messages:
* For a SIP Reply it returns true if the reply belongs to an existing
transaction and false otherwise.
* For a CANCEL it behaves exactly as t_lookup_cancel(): returns true
if a corresponding INVITE transaction exists for the CANCEL and
false otherwise.
* For ACKs to negative replies or for ACKs to local transactions it
will terminate the script if the ACK belongs to a transaction (it
would make very little sense to process an ACK to a negative reply
for an existing transaction in some other way then to simply pass
it to tm) or return false if not.
* For end-to-end ACKs (ACKs to 2xx responses for forwarded INVITE
transactions) it will return true if the corresponding INVITE
transaction is found and still active and false if not.

Note
Note that the e2e ACK matching is more of a hint then a certainty.
A delayed e2e ACK might arrive after the transaction wait time
elapses, when the INVITE transaction no longer exists and thus
would not match anything. There are also cases when tm would not
keep all the information needed for e2e ACK matching (since this is
not needed for a statefull proxy and it requires additional memory,
tm will not keep this information unless needed by some other
module or callbacks).
* For other requests (non ACKs and non CANCELs), it will terminate
the script for retransmissions and return false for new requests
(for which no transaction exists yet).

Note

An important difference from kamailio version is that for an ACK to
negative reply or for a local transaction, the script execution will be
immediately stopped and the message handled by tm, instead of returning
true.

t_check_trans() functionality for requests, except for the e2e ACK
matching, can be replicated in the script using t_lookup_cancel() and
t_lookup_request().

See also: t_lookup_request(), t_lookup_cancel().

Example 69. t_check_trans usage
if ( method == "CANCEL" && !t_check_trans())
sl_reply("403", "cancel out of the blue forbidden");
# note: in this example t_check_trans() can be replaced by t_lookup_cancel()

1.4.34. t_set_disable_6xx(0|1)

Turn off/on 6xx replies special rfc conformant handling on a per
transaction basis. If turned off (t_set_disable_6xx("1")) 6XXs will be
treated like normal replies.

It overrides the disable_6xx_block value for the current transaction.

See also: disable_6xx_block.

Example 70. t_set_disable_6xx usage
...
route {
...
if (src_ip==1.2.3.4) # bad user agent that sends 603
t_set_disable_6xx(1); # turn off 6xx special handling
...
}

1.4.35. t_set_disable_failover(0|1)

Turn off/on dns failover on a per transaction basis.

See also: use_dns_failover.

Example 71. t_set_disable_failover usage
...
route {
...
if (uri=~"@foo.bar$")
t_set_disable_failover(1); # turn off dns failover
...
}

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:[]\n
\n
\n
\n
\n
\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:[email protected]
sip:[email protected]
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.