[sr-dev] git:master: tmx: documentation for t_precheck_trans()

[Daniel-Constantin Mierla]

Module: sip-router
Branch: master
Commit: 392becb3e592f06f4ff843b303f1ddc765fa1a9f
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=392becb3e592f06f4ff843b303f1ddc765fa1a9f

Author: Daniel-Constantin Mierla <miconda at gmail.com>
Committer: Daniel-Constantin Mierla <miconda at gmail.com>
Date:   Mon Aug 18 22:05:30 2014 +0200

tmx: documentation for t_precheck_trans()

---

 modules/tmx/README            |   28 +++++++++++++++++++++++++++-
 modules/tmx/doc/tmx_admin.xml |   35 +++++++++++++++++++++++++++++++++--
 2 files changed, 60 insertions(+), 3 deletions(-)

diff --git a/modules/tmx/README b/modules/tmx/README
index 73eba24..80e6a45 100644
--- a/modules/tmx/README
+++ b/modules/tmx/README
@@ -47,6 +47,7 @@ Juha Heinanen
               3.8. t_suspend()
               3.9. t_continue(tindex, tlabel, rtname)
               3.10. t_reuse_branch()
+              3.11. t_precheck_trans()
 
         4. Exported pseudo-variables
         5. MI Commands
@@ -83,6 +84,7 @@ Juha Heinanen
    1.8. t_suspend usage
    1.9. t_continue usage
    1.10. t_reuse_branch usage
+   1.11. t_precheck_trans usage
 
 Chapter 1. Admin Guide
 
@@ -106,6 +108,7 @@ Chapter 1. Admin Guide
         3.8. t_suspend()
         3.9. t_continue(tindex, tlabel, rtname)
         3.10. t_reuse_branch()
+        3.11. t_precheck_trans()
 
    4. Exported pseudo-variables
    5. MI Commands
@@ -135,7 +138,7 @@ Chapter 1. Admin Guide
    This module collects extensions from Kamailio TM module.
 
    Kamailio TM (Transaction Management) module documentation is available
-   at: http://www.kamailio.org/docs/modules/1.5.x/tm.html
+   at: http://www.kamailio.org/docs/modules/stable/tm.html
 
 2. Dependencies
 
@@ -165,6 +168,7 @@ Chapter 1. Admin Guide
    3.8. t_suspend()
    3.9. t_continue(tindex, tlabel, rtname)
    3.10. t_reuse_branch()
+   3.11. t_precheck_trans()
 
 3.1. t_cancel_branches(which)
 
@@ -350,6 +354,28 @@ event_route [tm:branch-failure:contact] {
 }
 ...
 
+3.11. t_precheck_trans()
+
+   Check if current processed message is handled by other process. This
+   function is useful to catch retransmissions before transaction is
+   created. The function returns true if the request is handled by another
+   process.
+
+   Note that ACK and CANCEL requests are not tracked by this function, the
+   return code being false for them.
+
+   This function can be used from REQUEST_ROUTE .
+
+   Example 1.11. t_precheck_trans usage
+...
+    # handle retransmissions
+    if(t_precheck_trans()) {
+        t_check_trans();
+        exit;
+    }
+    t_check_trans();
+...
+
 4. Exported pseudo-variables
 
      * $T_branch_idx
diff --git a/modules/tmx/doc/tmx_admin.xml b/modules/tmx/doc/tmx_admin.xml
index 643281b..029c943 100644
--- a/modules/tmx/doc/tmx_admin.xml
+++ b/modules/tmx/doc/tmx_admin.xml
@@ -20,8 +20,8 @@
 	</para>
 	<para>
 	&kamailio; TM (Transaction Management) module documentation is available at:
-	<ulink url="http://www.kamailio.org/docs/modules/1.5.x/tm.html">
-	http://www.kamailio.org/docs/modules/1.5.x/tm.html</ulink>
+	<ulink url="http://www.kamailio.org/docs/modules/stable/tm.html">
+	http://www.kamailio.org/docs/modules/stable/tm.html</ulink>
 	</para>
 	</section>
 	
@@ -370,6 +370,37 @@ event_route [tm:branch-failure:contact] {
 </programlisting>
 		</example>
 	</section>
+	<section>
+		<title>
+		<function moreinfo="none">t_precheck_trans()</function>
+		</title>
+		<para>
+		Check if current processed message is handled by other process.
+		This function is useful to catch retransmissions before transaction
+		is created. The function returns true if the request is handled by
+		another process.
+		</para>
+		<para>
+		Note that ACK and CANCEL requests are not tracked by this function,
+		the return code being false for them.
+		</para>
+		<para>
+		This function can be used from REQUEST_ROUTE .
+		</para>
+		<example>
+		<title><function>t_precheck_trans</function> usage</title>
+		<programlisting format="linespecific">
+...
+    # handle retransmissions
+    if(t_precheck_trans()) {
+        t_check_trans();
+        exit;
+    }
+    t_check_trans();
+...
+</programlisting>
+		</example>
+	</section>
 
 	</section>