tmx: documented precheck_trans parameter

modules/tmx/README

@@ -35,56 +35,61 @@ Juha Heinanen
               2.1. Kamailio Modules
               2.2. External Libraries or Applications
 
-        3. Functions
-
-              3.1. t_cancel_branches(which)
-              3.2. t_cancel_callid(callid, cseq, flag [, rcode])
-              3.3. t_reply_callid(callid, cseq, code, reason)
-              3.4. t_flush_flags()
-              3.5. t_is_failure_route()
-              3.6. t_is_branch_route()
-              3.7. t_is_reply_route()
-              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
-
-              5.1. t_uac_dlg
-              5.2. t_uac_cancel
-              5.3. t_hash
-              5.4. t_reply
-              5.5. t_reply_callid
-
-        6. Statistics
-
-              6.1. received_replies
-              6.2. relayed_replies
-              6.3. local_replies
-              6.4. UAS_transactions
-              6.5. UAC_transactions
-              6.6. 2xx_transactions
-              6.7. 3xx_transactions
-              6.8. 4xx_transactions
-              6.9. 5xx_transactions
-              6.10. 6xx_transactions
-              6.11. inuse_transactions
+        3. Parameters
+
+              3.1. precheck_trans
+
+        4. Functions
+
+              4.1. t_cancel_branches(which)
+              4.2. t_cancel_callid(callid, cseq, flag [, rcode])
+              4.3. t_reply_callid(callid, cseq, code, reason)
+              4.4. t_flush_flags()
+              4.5. t_is_failure_route()
+              4.6. t_is_branch_route()
+              4.7. t_is_reply_route()
+              4.8. t_suspend()
+              4.9. t_continue(tindex, tlabel, rtname)
+              4.10. t_reuse_branch()
+              4.11. t_precheck_trans()
+
+        5. Exported pseudo-variables
+        6. MI Commands
+
+              6.1. t_uac_dlg
+              6.2. t_uac_cancel
+              6.3. t_hash
+              6.4. t_reply
+              6.5. t_reply_callid
+
+        7. Statistics
+
+              7.1. received_replies
+              7.2. relayed_replies
+              7.3. local_replies
+              7.4. UAS_transactions
+              7.5. UAC_transactions
+              7.6. 2xx_transactions
+              7.7. 3xx_transactions
+              7.8. 4xx_transactions
+              7.9. 5xx_transactions
+              7.10. 6xx_transactions
+              7.11. inuse_transactions
 
    List of Examples
 
-   1.1. t_cancel_branches usage
-   1.2. t_cancel_callid usage
-   1.3. t_reply_callid usage
-   1.4. t_flush_flags usage
-   1.5. t_is_failure_route usage
-   1.6. t_is_branch_route usage
-   1.7. t_is_reply_route usage
-   1.8. t_suspend usage
-   1.9. t_continue usage
-   1.10. t_reuse_branch usage
-   1.11. t_precheck_trans usage
+   1.1. precheck_trans usage
+   1.2. t_cancel_branches usage
+   1.3. t_cancel_callid usage
+   1.4. t_reply_callid usage
+   1.5. t_flush_flags usage
+   1.6. t_is_failure_route usage
+   1.7. t_is_branch_route usage
+   1.8. t_is_reply_route usage
+   1.9. t_suspend usage
+   1.10. t_continue usage
+   1.11. t_reuse_branch usage
+   1.12. t_precheck_trans usage
 
 Chapter 1. Admin Guide
 
@@ -96,42 +101,46 @@ Chapter 1. Admin Guide
         2.1. Kamailio Modules
         2.2. External Libraries or Applications
 
-   3. Functions
-
-        3.1. t_cancel_branches(which)
-        3.2. t_cancel_callid(callid, cseq, flag [, rcode])
-        3.3. t_reply_callid(callid, cseq, code, reason)
-        3.4. t_flush_flags()
-        3.5. t_is_failure_route()
-        3.6. t_is_branch_route()
-        3.7. t_is_reply_route()
-        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
-
-        5.1. t_uac_dlg
-        5.2. t_uac_cancel
-        5.3. t_hash
-        5.4. t_reply
-        5.5. t_reply_callid
-
-   6. Statistics
-
-        6.1. received_replies
-        6.2. relayed_replies
-        6.3. local_replies
-        6.4. UAS_transactions
-        6.5. UAC_transactions
-        6.6. 2xx_transactions
-        6.7. 3xx_transactions
-        6.8. 4xx_transactions
-        6.9. 5xx_transactions
-        6.10. 6xx_transactions
-        6.11. inuse_transactions
+   3. Parameters
+
+        3.1. precheck_trans
+
+   4. Functions
+
+        4.1. t_cancel_branches(which)
+        4.2. t_cancel_callid(callid, cseq, flag [, rcode])
+        4.3. t_reply_callid(callid, cseq, code, reason)
+        4.4. t_flush_flags()
+        4.5. t_is_failure_route()
+        4.6. t_is_branch_route()
+        4.7. t_is_reply_route()
+        4.8. t_suspend()
+        4.9. t_continue(tindex, tlabel, rtname)
+        4.10. t_reuse_branch()
+        4.11. t_precheck_trans()
+
+   5. Exported pseudo-variables
+   6. MI Commands
+
+        6.1. t_uac_dlg
+        6.2. t_uac_cancel
+        6.3. t_hash
+        6.4. t_reply
+        6.5. t_reply_callid
+
+   7. Statistics
+
+        7.1. received_replies
+        7.2. relayed_replies
+        7.3. local_replies
+        7.4. UAS_transactions
+        7.5. UAC_transactions
+        7.6. 2xx_transactions
+        7.7. 3xx_transactions
+        7.8. 4xx_transactions
+        7.9. 5xx_transactions
+        7.10. 6xx_transactions
+        7.11. inuse_transactions
 
 1. Overview
 
@@ -156,21 +165,38 @@ Chapter 1. Admin Guide
    running Kamailio with this module loaded:
      * None.
 
-3. Functions
+3. Parameters
 
-   3.1. t_cancel_branches(which)
-   3.2. t_cancel_callid(callid, cseq, flag [, rcode])
-   3.3. t_reply_callid(callid, cseq, code, reason)
-   3.4. t_flush_flags()
-   3.5. t_is_failure_route()
-   3.6. t_is_branch_route()
-   3.7. t_is_reply_route()
-   3.8. t_suspend()
-   3.9. t_continue(tindex, tlabel, rtname)
-   3.10. t_reuse_branch()
-   3.11. t_precheck_trans()
+   3.1. precheck_trans
 
-3.1. t_cancel_branches(which)
+3.1. precheck_trans
+
+   Enable/disable transaction pre-check via t_precheck_trans() function.
+   If set to 0, the internal structures are not created at startup and the
+   funcation will return false always.
+
+   Default value is 1 (enabled).
+
+   Example 1.1. precheck_trans usage
+...
+modparam("tmx", "precheck_trans", 0)
+...
+
+4. Functions
+
+   4.1. t_cancel_branches(which)
+   4.2. t_cancel_callid(callid, cseq, flag [, rcode])
+   4.3. t_reply_callid(callid, cseq, code, reason)
+   4.4. t_flush_flags()
+   4.5. t_is_failure_route()
+   4.6. t_is_branch_route()
+   4.7. t_is_reply_route()
+   4.8. t_suspend()
+   4.9. t_continue(tindex, tlabel, rtname)
+   4.10. t_reuse_branch()
+   4.11. t_precheck_trans()
+
+4.1. t_cancel_branches(which)
 
    Cancel branches of an active SIP transaction. The function can be
    called for a SIP reply that will identify the current branch.
@@ -182,14 +208,14 @@ Chapter 1. Admin Guide
 
    This function can be used in ONREPLY_ROUTE.
 
-   Example 1.1. t_cancel_branches usage
+   Example 1.2. t_cancel_branches usage
 ...
 if (t_cancel_branches("all")) {
         xlog("cancelled all branches\n");
 }
 ...
 
-3.2. t_cancel_callid(callid, cseq, flag [, rcode])
+4.2. t_cancel_callid(callid, cseq, flag [, rcode])
 
    Cancel first INVITE transaction identified by callid and cseq. It sets
    the flag if the value is greater than zero
@@ -203,7 +229,7 @@ if (t_cancel_branches("all")) {
 
    This function can be used in ANY_ROUTE.
 
-   Example 1.2. t_cancel_callid usage
+   Example 1.3. t_cancel_callid usage
 ...
 if (t_cancel_callid("123qaz", "5", "22")) {
         xlog("transaction cancelled\n");
@@ -214,7 +240,7 @@ if (t_cancel_callid("123qaz", "5", "22", "200")) {
 }
 ...
 
-3.3. t_reply_callid(callid, cseq, code, reason)
+4.3. t_reply_callid(callid, cseq, code, reason)
 
    Send reply to first INVITE transaction identified by callid and cseq.
 
@@ -226,14 +252,14 @@ if (t_cancel_callid("123qaz", "5", "22", "200")) {
 
    This function can be used in ANY_ROUTE.
 
-   Example 1.3. t_reply_callid usage
+   Example 1.4. t_reply_callid usage
 ...
 if (t_reply_callid("123qaz", "5", "458", "Replied remotely")) {
         xlog("transaction replied\n");
 }
 ...
 
-3.4. t_flush_flags()
+4.4. t_flush_flags()
 
    Flush the flags from current SIP message into the already created
    transaction. It make sense only in routing block if the transaction was
@@ -241,18 +267,18 @@ if (t_reply_callid("123qaz", "5", "458", "Replied remotely")) {
 
    This function can be used from ANY_ROUTE .
 
-   Example 1.4. t_flush_flags usage
+   Example 1.5. t_flush_flags usage
 ...
 t_flush_flags();
 ...
 
-3.5. t_is_failure_route()
+4.5. t_is_failure_route()
 
    Returns true if the top-executed route block is failure_route.
 
    This function can be used from ANY_ROUTE .
 
-   Example 1.5. t_is_failure_route usage
+   Example 1.6. t_is_failure_route usage
 ...
 failure_route[xyz] {
     route(abc);
@@ -263,13 +289,13 @@ route[abc] {
 }
 ...
 
-3.6. t_is_branch_route()
+4.6. t_is_branch_route()
 
    Returns true if the top-executed route block is branch_route.
 
    This function can be used from ANY_ROUTE .
 
-   Example 1.6. t_is_branch_route usage
+   Example 1.7. t_is_branch_route usage
 ...
 branch_route[xyz] {
     route(abc);
@@ -280,13 +306,13 @@ route[abc] {
 }
 ...
 
-3.7. t_is_reply_route()
+4.7. t_is_reply_route()
 
    Returns true if the top-executed route block is reply_route.
 
    This function can be used from ANY_ROUTE .
 
-   Example 1.7. t_is_reply_route usage
+   Example 1.8. t_is_reply_route usage
 ...
 reply_route[xyz] {
     route(abc);
@@ -297,7 +323,7 @@ route[abc] {
 }
 ...
 
-3.8. t_suspend()
+4.8. t_suspend()
 
    Suspend the execution of SIP request in a transaction. If transaction
    was not created yet, it is created by this function. Returns true in
@@ -306,7 +332,7 @@ route[abc] {
 
    This function can be used from ANY_ROUTE .
 
-   Example 1.8. t_suspend usage
+   Example 1.9. t_suspend usage
 ...
 if(t_suspend())
 {
@@ -315,7 +341,7 @@ if(t_suspend())
 }
 ...
 
-3.9. t_continue(tindex, tlabel, rtname)
+4.9. t_continue(tindex, tlabel, rtname)
 
    Continue the execution of the transaction identified by tindex and
    tlabel with the actions defined in route[rtname].
@@ -330,12 +356,12 @@ if(t_suspend())
 
    This function can be used in ANY_ROUTE.
 
-   Example 1.9. t_continue usage
+   Example 1.10. t_continue usage
 ...
 t_continue('123', '456', 'MYROUTE');
 ...
 
-3.10. t_reuse_branch()
+4.10. t_reuse_branch()
 
    Creates new "main" branch by making copy of branch-failure branch.
    Currently the following branch attributes are copied from
@@ -344,7 +370,7 @@ t_continue('123', '456', 'MYROUTE');
 
    This function can be used from tm:branch-failure event_route.
 
-   Example 1.10. t_reuse_branch usage
+   Example 1.11. t_reuse_branch usage
 ...
 event_route [tm:branch-failure:contact] {
     t_reuse_branch();
@@ -354,7 +380,7 @@ event_route [tm:branch-failure:contact] {
 }
 ...
 
-3.11. t_precheck_trans()
+4.11. t_precheck_trans()
 
    Check if current processed message is handled by other process. This
    function is useful to catch retransmissions before transaction is
@@ -366,7 +392,7 @@ event_route [tm:branch-failure:contact] {
 
    This function can be used from REQUEST_ROUTE .
 
-   Example 1.11. t_precheck_trans usage
+   Example 1.12. t_precheck_trans usage
 ...
     # handle retransmissions
     if(t_precheck_trans()) {
@@ -376,7 +402,7 @@ event_route [tm:branch-failure:contact] {
     t_check_trans();
 ...
 
-4. Exported pseudo-variables
+5. Exported pseudo-variables
 
      * $T_branch_idx
      * $T_reply_code
@@ -390,15 +416,15 @@ event_route [tm:branch-failure:contact] {
    Exported pseudo-variables are documented at
    http://www.kamailio.org/wiki/.
 
-5. MI Commands
+6. MI Commands
 
-   5.1. t_uac_dlg
-   5.2. t_uac_cancel
-   5.3. t_hash
-   5.4. t_reply
-   5.5. t_reply_callid
+   6.1. t_uac_dlg
+   6.2. t_uac_cancel
+   6.3. t_hash
+   6.4. t_reply
+   6.5. t_reply_callid
 
-5.1. t_uac_dlg
+6.1. t_uac_dlg
 
    Generates and sends a local SIP request.
 
@@ -413,7 +439,7 @@ event_route [tm:branch-failure:contact] {
      * body - (optional, may not be present) request body (if present,
        requires the "Content-Type" and "Content-length" headers)
 
-5.2. t_uac_cancel
+6.2. t_uac_cancel
 
    Generates and sends a CANCEL for an existing local SIP request.
 
@@ -421,14 +447,14 @@ event_route [tm:branch-failure:contact] {
      * callid - callid of the INVITE request to be cancelled.
      * cseq - cseq of the INVITE request to be cancelled.
 
-5.3. t_hash
+6.3. t_hash
 
    Gets information about the load of TM internal hash table.
 
    Parameters:
      * none
 
-5.4. t_reply
+6.4. t_reply
 
    Generates and sends a reply for an existing inbound SIP transaction.
 
@@ -442,7 +468,7 @@ event_route [tm:branch-failure:contact] {
      * body - (optional, may not be present) reply body (if present,
        requires the "Content-Type" and "Content-length" headers)
 
-5.5. t_reply_callid
+6.5. t_reply_callid
 
    Generates and sends a reply for an existing inbound SIP transaction.
 
@@ -457,63 +483,63 @@ event_route [tm:branch-failure:contact] {
      * body - (optional, may not be present) reply body (if present,
        requires the "Content-Type" and "Content-length" headers)
 
-6. Statistics
+7. Statistics
 
-   6.1. received_replies
-   6.2. relayed_replies
-   6.3. local_replies
-   6.4. UAS_transactions
-   6.5. UAC_transactions
-   6.6. 2xx_transactions
-   6.7. 3xx_transactions
-   6.8. 4xx_transactions
-   6.9. 5xx_transactions
-   6.10. 6xx_transactions
-   6.11. inuse_transactions
+   7.1. received_replies
+   7.2. relayed_replies
+   7.3. local_replies
+   7.4. UAS_transactions
+   7.5. UAC_transactions
+   7.6. 2xx_transactions
+   7.7. 3xx_transactions
+   7.8. 4xx_transactions
+   7.9. 5xx_transactions
+   7.10. 6xx_transactions
+   7.11. inuse_transactions
 
    Exported statistics are listed in the next sections. All statistics
    except "inuse_transactions" can be reset.
 
-6.1. received_replies
+7.1. received_replies
 
    Total number of total replies received by TM module.
 
-6.2. relayed_replies
+7.2. relayed_replies
 
    Total number of replies received and relayed by TM module.
 
-6.3. local_replies
+7.3. local_replies
 
    Total number of replies local generated by TM module.
 
-6.4. UAS_transactions
+7.4. UAS_transactions
 
    Total number of transactions created by received requests.
 
-6.5. UAC_transactions
+7.5. UAC_transactions
 
    Total number of transactions created by local generated requests.
 
-6.6. 2xx_transactions
+7.6. 2xx_transactions
 
    Total number of transactions completed with 2xx replies.
 
-6.7. 3xx_transactions
+7.7. 3xx_transactions
 
    Total number of transactions completed with 3xx replies.
 
-6.8. 4xx_transactions
+7.8. 4xx_transactions
 
    Total number of transactions completed with 4xx replies.
 
-6.9. 5xx_transactions
+7.9. 5xx_transactions
 
    Total number of transactions completed with 5xx replies.
 
-6.10. 6xx_transactions
+7.10. 6xx_transactions
 
    Total number of transactions completed with 6xx replies.
 
-6.11. inuse_transactions
+7.11. inuse_transactions
 
    Number of transactions existing in memory at current time.

modules/tmx/doc/tmx_admin.xml

@@ -56,6 +56,31 @@
 	</section>
 	</section>
 
+	<section>
+	<title>Parameters</title>
+	<section id="tmx.p.precheck_trans">
+		<title>
+		<function moreinfo="none">precheck_trans</function>
+		</title>
+		<para>
+		Enable/disable transaction pre-check via t_precheck_trans()
+		function. If set to 0, the internal structures are not created
+		at startup and the funcation will return false always.
+		</para>
+		<para>
+		Default value is <emphasis>1</emphasis> (enabled).
+		</para>
+		<example>
+		<title><function>precheck_trans</function> usage</title>
+		<programlisting format="linespecific">
+...
+modparam("tmx", "precheck_trans", 0)
+...
+</programlisting>
+		</example>
+	</section>
+	</section>
+
 	<section>
 	<title>Functions</title>
 	<section>
@@ -344,8 +369,7 @@ t_continue('123', '456', 'MYROUTE');
 
 	<section>
 		<title>
-		<function moreinfo="none">t_reuse_branch()
-		</function>
+		<function moreinfo="none">t_reuse_branch()</function>
 		</title>
 		<para>
 		Creates new "main" branch by making copy of branch-failure
@@ -370,7 +394,7 @@ event_route [tm:branch-failure:contact] {
 </programlisting>
 		</example>
 	</section>
-	<section>
+	<section id="tmx.f.t_precheck_trans">
 		<title>
 		<function moreinfo="none">t_precheck_trans()</function>
 		</title>