[sr-dev] git:master: tm doc: t_check_trans and note about fr_timer_avp

Module: sip-router Branch: master Commit: c263b1a7a83f7143093e699754b377647d54496d URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=c263b1a… Author: Andrei Pelinescu-Onciul &lt;andrei(a)iptel.org&gt; Committer: Andrei Pelinescu-Onciul &lt;andrei(a)iptel.org&gt; Date: Mon Jun 22 17:26:47 2009 +0200 tm doc: t_check_trans and note about fr_timer_avp - added missing t_check_trans docs - added fr_timer_avp and fr_inv_timer_avp notes about new empty/zero avp value handling (use default value) and about using seconds instead of milliseconds. --- modules/tm/doc/functions.xml | 75 ++++++++++++++++++++++++++++++++++++++++++ modules/tm/doc/params.xml | 30 ++++++++++++++-- 2 files changed, 101 insertions(+), 4 deletions(-) diff --git a/modules/tm/doc/functions.xml b/modules/tm/doc/functions.xml index 70309a5..d3b21d0 100644 --- a/modules/tm/doc/functions.xml +++ b/modules/tm/doc/functions.xml @@ -1104,4 +1104,79 @@ if (!t_next_contacts()) { </example> </section> + <section id="t_check_trans"> + <title> + <function>t_check_trans()</function> + </title> + <para> + <function>t_check_trans()</function> can be used to quickly check if + a message belongs or is related to a transaction. It behaves + differently for different types of messages: + <itemizedlist> + <listitem> + <para>For a SIP Reply it returns true if the reply belongs to + an existing transaction and false otherwise.</para> + </listitem> + <listitem> + <para>For a CANCEL it behaves exactly as + <function>t_lookup_cancel()</function>: returns true if a + corresponding INVITE transaction exists for the CANCEL and + false otherwise.</para> + </listitem> + <listitem> + <para>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.</para> + </listitem> + <listitem> + <para>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. + </para> + <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). + </note> + </listitem> + <listitem> + <para>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).</para> + </listitem> + </itemizedlist> + </para> + <note><para> + 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. + </para></note> + <para><function>t_check_trans()</function> functionality for requests, + except for the e2e ACK matching, can be replicated in the script + using <function>t_lookup_cancel()</function> and + <function>t_lookup_request()</function>. + </para> + <para>See also: <function>t_lookup_request()</function>, + <function>t_lookup_cancel()</function>. + </para> + <example> + <title><function>t_check_trans</function> usage</title> + <programlisting> + +if ( method == "CANCEL" &amp;&amp; !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() + + </programlisting> + </example> + </section> + </section> diff --git a/modules/tm/doc/params.xml b/modules/tm/doc/params.xml index ddfcb29..7df9f13 100644 --- a/modules/tm/doc/params.xml +++ b/modules/tm/doc/params.xml @@ -809,6 +809,17 @@ modparam("tm", "contacts_avp", "$avp(i:25)") The value of this parameter is the the name of the AVP to be checked, without the $ character or "$avp" prefix. </para> + <note><para> + The value of the AVP is expected to be expressed in + <emphasis>seconds</emphasis> and not milliseconds (unlike the rest + of the timers). + </para></note> + <para> + 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 + <function>t_set_fr()</function> on a per transaction basis. + </para> <para> See also: <function>t_set_fr()</function>, <varname>fr_timer</varname>. @@ -830,15 +841,26 @@ modparam("tm", "fr_timer_avp", "i:708") 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_inv_timer timer, - effectively overriding the value configured in - <varname>fr_inv_timer</varname> parameter for the current - transaction. + 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 <varname>fr_inv_timer</varname> parameter for the + current transaction. </para> <para> The value of this parameter is the the name of the AVP to be checked, without the $ character or "$avp" prefix. </para> + <note><para> + The value of the AVP is expected to be expressed in + <emphasis>seconds</emphasis> and not milliseconds (unlike the rest + of the timers). + </para></note> + <para> + 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 + <function>t_set_fr()</function> on a per transaction basis. + </para> <para> See also: <function>t_set_fr()</function>, <varname>fr_inv_timer</varname>.