diff --git a/modules/tm/README b/modules/tm/README index 3e1ebecfb2b..c36f42a89ed 100644 --- a/modules/tm/README +++ b/modules/tm/README @@ -1634,7 +1634,7 @@ modparam("tm|usrloc", "xavp_contact", "ulattrs") 5.50. t_use_uac_headers() 5.51. t_is_retr_async_reply() -5.1. t_relay([host, port]) +5.1. 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 @@ -1662,7 +1662,7 @@ if (!t_relay()) }; ... -5.2. t_relay_to_udp([ip, port]) +5.2. t_relay_to_udp([ip, port]) Relay a message statefully using a fixed protocol either to the specified fixed destination or to a destination derived from the @@ -1688,19 +1688,19 @@ else t_relay_to_tcp(); # relay to msg. uri, but over tcp ... -5.3. t_relay_to_tcp([ip, port]) +5.3. t_relay_to_tcp([ip, port]) See function t_relay_to_udp([ip, port]). -5.4. t_relay_to_tls([ip, port]) +5.4. t_relay_to_tls([ip, port]) See function t_relay_to_udp([ip, port]). -5.5. t_relay_to_sctp([ip, port]) +5.5. t_relay_to_sctp([ip, port]) See function t_relay_to_udp([ip, port]). -5.6. t_on_failure(failure_route) +5.6. 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 @@ -1737,7 +1737,7 @@ failure_route[1] { See test/onr.cfg for a more complex example of combination of serial with parallel forking. -5.7. t_on_branch_failure(branch_failure_route) +5.7. t_on_branch_failure(branch_failure_route) Sets the branch_failure routing block, to which control is passed on each negative response to a transaction. This route is run before @@ -1770,7 +1770,7 @@ event_route[tm:branch-failure:myroute] { } ... -5.8. t_on_reply(onreply_route) +5.8. 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 @@ -1800,7 +1800,7 @@ es'); } } -5.9. t_on_branch(branch_route) +5.9. 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 @@ -1824,7 +1824,7 @@ branch_route[1] { } } -5.10. t_newtran() +5.10. 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. @@ -1840,7 +1840,7 @@ if (t_newtran()) { See test/uas.cfg for more examples. -5.11. t_reply(code, reason_phrase) +5.11. t_reply(code, reason_phrase) Sends a stateful reply after a transaction has been established. See t_newtran for usage. @@ -1865,7 +1865,7 @@ if (t_newtran()) { t_reply("404", "Not found"); ... -5.12. t_lookup_request() +5.12. 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 @@ -1880,7 +1880,7 @@ if (t_lookup_request()) { }; ... -5.13. t_retransmit_reply() +5.13. t_retransmit_reply() Retransmits a reply sent previously by UAS transaction. @@ -1889,7 +1889,7 @@ if (t_lookup_request()) { t_retransmit_reply(); ... -5.14. t_release() +5.14. t_release() Remove transaction from memory (it will be first put on a wait timer to absorb delayed messages). @@ -1899,7 +1899,7 @@ t_retransmit_reply(); t_release(); ... -5.15. t_forward_nonack([ip, port]) +5.15. t_forward_nonack([ip, port]) Mainly for internal usage -- forward a non-ACK request statefully. Variants of this functions can enforce a specific transport protocol. @@ -1913,23 +1913,23 @@ t_release(); t_forward_nonack("1.2.3.4", "5060"); ... -5.16. t_forward_nonack_udp(ip, port) +5.16. t_forward_nonack_udp(ip, port) See function t_forward_nonack([ip, port]). -5.17. t_forward_nonack_tcp(ip, port) +5.17. t_forward_nonack_tcp(ip, port) See function t_forward_nonack([ip, port]). -5.18. t_forward_nonack_tls(ip, port) +5.18. t_forward_nonack_tls(ip, port) See function t_forward_nonack([ip, port]). -5.19. t_forward_nonack_sctp(ip, port) +5.19. t_forward_nonack_sctp(ip, port) See function t_forward_nonack([ip, port]). -5.20. t_set_fr(fr_inv_timeout [, fr_timeout]) +5.20. 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 @@ -1963,7 +1963,7 @@ branch_route[1] { } } -5.21. t_reset_fr() +5.21. 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 @@ -1982,7 +1982,7 @@ route { ... } -5.22. t_set_max_lifetime(inv_lifetime, noninv_lifetime) +5.22. 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 @@ -2011,7 +2011,7 @@ route { # INVITE and to 15s if not } -5.23. t_reset_max_lifetime() +5.23. 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 @@ -2030,7 +2030,7 @@ route { ... } -5.24. t_set_retr(retr_t1_interval, retr_t2_interval) +5.24. 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 @@ -2076,7 +2076,7 @@ branch_route[1] { } } -5.25. t_reset_retr() +5.25. 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 @@ -2095,7 +2095,7 @@ route { ... } -5.26. t_set_auto_inv_100(0|1) +5.26. 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 @@ -2112,7 +2112,7 @@ route { ... } -5.27. t_branch_timeout() +5.27. t_branch_timeout() Returns true if the failure route is executed for a branch that did timeout. It can be used from failure_route and branch-failure event @@ -2127,7 +2127,7 @@ failure_route[0]{ } } -5.28. t_branch_replied() +5.28. 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 @@ -2146,7 +2146,7 @@ failure_route[0]{ } } -5.29. t_any_timeout() +5.29. t_any_timeout() Returns true if at least one of the current transactions branches did timeout. @@ -2162,7 +2162,7 @@ failure_route[0]{ } } -5.30. t_any_replied() +5.30. 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 @@ -2177,7 +2177,7 @@ onreply_route[0]{ } } -5.31. t_grep_status("code") +5.31. 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. @@ -2191,7 +2191,7 @@ onreply_route[0]{ } } -5.32. t_is_canceled() +5.32. t_is_canceled() Returns true if the current transaction was canceled. @@ -2204,7 +2204,7 @@ failure_route[0]{ } } -5.33. t_is_expired() +5.33. 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. @@ -2218,7 +2218,7 @@ failure_route[0]{ } } -5.34. t_relay_cancel() +5.34. 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, @@ -2243,7 +2243,7 @@ if (method == CANCEL) { # do the same as for INVITEs } -5.35. t_lookup_cancel([1]) +5.35. 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 @@ -2275,7 +2275,7 @@ if (method == CANCEL) { # do the same as for INVITEs } -5.36. t_drop_replies([mode]) +5.36. t_drop_replies([mode]) Drops all the previously received replies in failure_route block to make sure that none of them is picked up again. @@ -2303,7 +2303,7 @@ failure_route[0]{ } } -5.37. t_save_lumps() +5.37. 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 @@ -2343,7 +2343,7 @@ failure_route[1] { t_relay(); } -5.38. t_load_contacts() +5.38. t_load_contacts() This is the first of the three functions that can be used to implement serial/parallel forking based on q and +sip.instance values of @@ -2385,7 +2385,7 @@ if (!t_load_contacts()) { }; ... -5.39. t_next_contacts() +5.39. t_next_contacts() Function t_next_contacts() is the second of the three functions that can be used to implement serial/parallel forking based on the q value @@ -2437,7 +2437,7 @@ if (!t_next_contacts()) { }; ... -5.40. t_next_contact_flow() +5.40. t_next_contact_flow() Function t_next_contact_flow() is the last of the three functions that can be used to implement serial/parallel forking based on the q value @@ -2467,7 +2467,7 @@ event_route[tm:branch-failure:outbound] } ... -5.41. t_check_status(re) +5.41. t_check_status(re) Returns true if the regular expresion "re" match the reply code of the response message as follows: @@ -2485,7 +2485,7 @@ if (t_check_status("(487)|(408)")) { } ... -5.42. t_check_trans() +5.42. 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 @@ -2537,7 +2537,7 @@ 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() -5.43. t_set_disable_6xx(0|1) +5.43. 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 @@ -2556,7 +2556,7 @@ route { ... } -5.44. t_set_disable_failover(0|1) +5.44. t_set_disable_failover(0|1) Turn off/on dns failover on a per transaction basis. @@ -2571,7 +2571,7 @@ route { ... } -5.45. t_set_disable_internal_reply(0|1) +5.45. t_set_disable_internal_reply(0|1) Turn off/on sending internally a SIP reply in case of relay errors. @@ -2583,7 +2583,7 @@ if(!t_relay()) { } ... -5.46. t_replicate([params]) +5.46. t_replicate([params]) Replicate the SIP request to a specific address. @@ -2619,7 +2619,7 @@ t_replicate("sip:$var(h);transport=tls"); t_replicate_to_udp("1.2.3.4", "5060"); ... -5.47. t_relay_to(proxy, flags) +5.47. t_relay_to(proxy, flags) Forward the SIP request to a specific address, controlling internal behavior via flags. @@ -2652,7 +2652,7 @@ t_relay_to("tls:1.2.3.4"); t_relay_to("0x01"); ... -5.48. t_set_no_e2e_cancel_reason(0|1) +5.48. t_set_no_e2e_cancel_reason(0|1) Enables/disables reason header (RFC 3326) copying from the triggering received CANCEL to the generated hop-by-hop CANCEL. 0 enables and 1 @@ -2661,6 +2661,9 @@ t_relay_to("0x01"); It overrides the e2e_cancel_reason setting (module parameter) for the current transaction. + Note: the function has to be used when processing the INVITE (not when + processing the CANCEL). + See also: e2e_cancel_reason. Example 1.87. t_set_no_e2e_cancel_reason usage @@ -2673,7 +2676,7 @@ opying ... } -5.49. t_is_set(target) +5.49. t_is_set(target) Return true if the attribute specified by 'target' is set for transaction. @@ -2692,7 +2695,7 @@ if(!t_is_set("failure_route")) LM_DBG("no failure route will be executed for current transaction\n"); ... -5.50. t_use_uac_headers() +5.50. t_use_uac_headers() Set internal flags to tell tm to use UAC side for building headers for local generated requests (ACK, CANCEL) - useful when changing From/To @@ -2705,7 +2708,7 @@ if(!t_is_set("failure_route")) t_use_uac_headers(); ... -5.51. t_is_retr_async_reply() +5.51. t_is_retr_async_reply() Check to see if the reply is a retransmitted reply on a transaction that is currently suspended asynchronously (suspended during reply @@ -2808,7 +2811,7 @@ end of body 6.2. Functions -6.2.1. register_tmcb(cb_type, cb_func) +6.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. @@ -2817,7 +2820,7 @@ end of body * cb_type - Callback type. * cb_func - Callback function. -6.2.2. load_tm(*import_structure) +6.2.2. load_tm(*import_structure) For programmatic use only--import exported TM functions. See the acc module for an example of use. @@ -2825,7 +2828,7 @@ end of body Meaning of the parameters is as follows: * import_structure - Pointer to the import structure. -6.2.3. int t_suspend(struct sip_msg *msg, unsigned int *hash_index, unsigned +6.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 @@ -2863,7 +2866,7 @@ int *label) t_suspend() should return 0 to make sure that the script processing does not continue. -6.2.4. int t_continue(unsigned int hash_index, unsigned int label, struct +6.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(), @@ -2879,7 +2882,7 @@ action *route) Return value: 0 - success, <0 - error. -6.2.5. int t_cancel_suspend(unsigned int hash_index, unsigned int label) +6.2.5. int t_cancel_suspend(unsigned int hash_index, unsigned int label) For programmatic use only. This function is for revoking t_suspend() from the same process as it was executed before. t_cancel_suspend() can @@ -2899,7 +2902,7 @@ action *route) 7.1. event_route[tm:branch-failure] -7.1. event_route[tm:branch-failure] +7.1. event_route[tm:branch-failure] Named branch failure routes can be defined to run when when a failure response is received. This allows handling failures on individual