[sr-dev] git:master: tm doc: t_check_trans and note about fr_timer_avp
Andrei Pelinescu-Onciul
andrei at iptel.org
Mon Jun 22 17:31:21 CEST 2009
Module: sip-router
Branch: master
Commit: c263b1a7a83f7143093e699754b377647d54496d
URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=c263b1a7a83f7143093e699754b377647d54496d
Author: Andrei Pelinescu-Onciul <andrei at iptel.org>
Committer: Andrei Pelinescu-Onciul <andrei at iptel.org>
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" && !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>.
More information about the sr-dev
mailing list