git:master: tmx: doxumented t_suspend() and t_continue() - sr-dev

3 Jul 2011

Module: sip-router
Branch: master
Commit: 492055eba80bfbbfeef3721ded47c2af603ae8f8
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=492055eb...
Author: Daniel-Constantin Mierla miconda@gmail.com
Committer: Daniel-Constantin Mierla miconda@gmail.com
Date:   Sun Jul  3 15:32:42 2011 +0200
tmx: doxumented t_suspend() and t_continue()
---
modules_k/tmx/README            |   88 +++++++++++++++++++++++++++++---------
 modules_k/tmx/doc/tmx_admin.xml |   65 ++++++++++++++++++++++++++++
 2 files changed, 132 insertions(+), 21 deletions(-)

diff --git a/modules_k/tmx/README b/modules_k/tmx/README
index 38ffdd7..8a0ed2b 100644
--- a/modules_k/tmx/README
+++ b/modules_k/tmx/README
@@ -11,7 +11,7 @@ Daniel-Constantin Mierla
miconda@gmail.com
-   Copyright © 2009 Daniel-Constantin Mierla
+   Copyright � 2009 Daniel-Constantin Mierla
      __________________________________________________________________
Table of Contents
@@ -32,6 +32,8 @@ Daniel-Constantin Mierla
               3.4. t_flush_flags()
               3.5. t_is_failure_route()
               3.6. t_is_branch_route()
+              3.7. t_suspend()
+              3.8. t_continue(tindex, tlabel, rtname)
4. Exported pseudo-variables
         5. Exported MI Functions
@@ -64,6 +66,8 @@ Daniel-Constantin Mierla
    1.4. t_flush_flags usage
    1.5. t_is_failure_route usage
    1.6. t_is_branch_route usage
+   1.7. t_suspend usage
+   1.8. t_continue usage
Chapter 1. Admin Guide
@@ -83,6 +87,8 @@ Chapter 1. Admin Guide
         3.4. t_flush_flags()
         3.5. t_is_failure_route()
         3.6. t_is_branch_route()
+        3.7. t_suspend()
+        3.8. t_continue(tindex, tlabel, rtname)
4. Exported pseudo-variables
    5. Exported MI Functions
@@ -138,8 +144,10 @@ Chapter 1. Admin Guide
    3.4. t_flush_flags()
    3.5. t_is_failure_route()
    3.6. t_is_branch_route()
+   3.7. t_suspend()
+   3.8. t_continue(tindex, tlabel, rtname)
-3.1.  t_cancel_branches(which)
+3.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.
@@ -158,7 +166,7 @@ if (t_cancel_branches("all")) {
 }
 ...
-3.2.  t_cancel_callid(callid, cseq, flag)
+3.2. t_cancel_callid(callid, cseq, flag)
Cancel first INVITE transaction identified by callid and cseq. It sets
    the flag if the value is greater than zero
@@ -177,7 +185,7 @@ if (t_cancel_callid("123qaz", "5", "22")) {
 }
 ...
-3.3.  t_reply_callid(callid, cseq, code, reason)
+3.3. t_reply_callid(callid, cseq, code, reason)
Send reply to first INVITE transaction identified by callid and cseq.
@@ -196,7 +204,7 @@ if (t_reply_callid("123qaz", "5", "458", "Replied remotely")) {
 }
 ...
-3.4.  t_flush_flags()
+3.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
@@ -209,7 +217,7 @@ if (t_reply_callid("123qaz", "5", "458", "Replied remotely")) {
 t_flush_flags();
 ...
-3.5.  t_is_failure_route()
+3.5. t_is_failure_route()
Returns true if the top-executed route block is failure_route.
@@ -226,7 +234,7 @@ route[abc] {
 }
 ...
-3.6.  t_is_branch_route()
+3.6. t_is_branch_route()
Returns true if the top-executed route block is branch_route.
@@ -243,6 +251,44 @@ route[abc] {
 }
 ...
+3.7. 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
+   case of success and internal transaction index and label are available
+   via $T(id_index) and $T(id_label).
+
+   This function can be used from ANY_ROUTE .
+
+   Example 1.7. t_suspend usage
+...
+if(t_suspend())
+{
+    xlog("proceesing suspended in trasaction [$T(id_index):$T(id_label)]\n");
+    exit;
+}
+...
+
+3.8. t_continue(tindex, tlabel, rtname)
+
+   Continue the execution of the transaction identified by tindex and
+   tlabel with the actions defined in route[rtname].
+
+   Parameters:.
+     * tindex - internal index of transaction. Can be an integer or a
+       pseudo-variable.
+     * tlabel - internal label of transaction. Can be an integer or a
+       pseudo-variable.
+     * rtname - the name of the route block to execute. Can be a static
+       string value or a dynamic string with pseudo-variables.
+
+   This function can be used in ANY_ROUTE.
+
+   Example 1.8. t_continue usage
+...
+tcontinue('123', '456', 'MYROUTE');
+...
+
 4. Exported pseudo-variables
* $T_branch_idx
@@ -261,22 +307,22 @@ route[abc] {
    5.4. t_reply
    5.5. t_reply_callid
-5.1.  t_uac_dlg
+5.1. t_uac_dlg
Generates and sends a local SIP request.
Parameters:
      * method - request method
      * RURI - request SIP URI
-     * NEXT HOP - next hop SIP URI (OBP); use “.” if no value.
-     * socket - local socket to be used for sending the request; use “.”
+     * NEXT HOP - next hop SIP URI (OBP); use "." if no value.
+     * socket - local socket to be used for sending the request; use "."
        if no value.
      * headers - set of additional headers to be added to the request; at
-       least “From” and “To” headers must be specify)
+       least "From" and "To" headers must be specify)
      * body - (optional, may not be present) request body (if present,
-       requires the “Content-Type” and “Content-length” headers)
+       requires the "Content-Type" and "Content-length" headers)
-5.2.  t_uac_cancel
+5.2. t_uac_cancel
Generates and sends a CANCEL for an existing local SIP request.
@@ -284,14 +330,14 @@ route[abc] {
      * callid - callid of the INVITE request to be cancelled.
      * cseq - cseq of the INVITE request to be cancelled.
-5.3.  t_hash
+5.3. t_hash
Gets information about the load of TM internal hash table.
Parameters:
      * none
-5.4.  t_reply
+5.4. t_reply
Generates and sends a reply for an existing inbound SIP transaction.
@@ -301,11 +347,11 @@ route[abc] {
      * trans_id - transaction identifier (has the hash_entry:label format)
      * to_tag - To tag to be added to TO header
      * new_headers - extra headers to be appended to the reply; use a dot
-       (“.”) char only if there are no headers;
+       (".") char only if there are no headers;
      * body - (optional, may not be present) reply body (if present,
-       requires the “Content-Type” and “Content-length” headers)
+       requires the "Content-Type" and "Content-length" headers)
-5.5.  t_reply_callid
+5.5. t_reply_callid
Generates and sends a reply for an existing inbound SIP transaction.
@@ -316,9 +362,9 @@ route[abc] {
      * cseq - SIP CSeq header
      * to_tag - To tag to be added to TO header
      * new_headers - extra headers to be appended to the reply; use a dot
-       (“.”) char only if there are no headers;
+       (".") char only if there are no headers;
      * body - (optional, may not be present) reply body (if present,
-       requires the “Content-Type” and “Content-length” headers)
+       requires the "Content-Type" and "Content-length" headers)
6. Exported statistics
@@ -335,7 +381,7 @@ route[abc] {
    6.11. inuse_transactions
Exported statistics are listed in the next sections. All statistics
-   except “inuse_transactions” can be reset.
+   except "inuse_transactions" can be reset.
6.1. received_replies
diff --git a/modules_k/tmx/doc/tmx_admin.xml b/modules_k/tmx/doc/tmx_admin.xml
index 86a8946..dfb85a3 100644
--- a/modules_k/tmx/doc/tmx_admin.xml
+++ b/modules_k/tmx/doc/tmx_admin.xml
@@ -242,6 +242,71 @@ route[abc] {
 </programlisting>
    	</example>
    </section>
+	<section>
+		<title>
+		<function moreinfo="none">t_suspend()</function>
+		</title>
+		<para>
+		Suspend the execution of SIP request in a transaction. If transaction
+		was not created yet, it is created by this function. Returns true in
+		case of success and internal transaction index and label are available
+		via $T(id_index) and $T(id_label).
+		</para>
+		<para>
+		This function can be used from ANY_ROUTE .
+		</para>
+		<example>
+		<title><function>t_suspend</function> usage</title>
+		<programlisting format="linespecific">
+...
+if(t_suspend())
+{
+    xlog("proceesing suspended in trasaction [$T(id_index):$T(id_label)]\n");
+    exit;
+}
+...
+</programlisting>
+		</example>
+	</section>
+	<section>
+		<title>
+			<function moreinfo="none">t_continue(tindex, tlabel, rtname)
+			</function>
+		</title>
+		<para>
+		Continue the execution of the transaction identified by tindex and
+		tlabel with the actions defined in route[rtname].
+		</para>
+		<para>
+		Parameters:.
+		</para>
+		<itemizedlist>
+			<listitem><para>
+				<emphasis>tindex</emphasis> - internal index of transaction.
+				Can be an integer or a pseudo-variable.
+			</para></listitem>
+			<listitem><para>
+				<emphasis>tlabel</emphasis> - internal label of transaction.
+				Can be an integer or a pseudo-variable.
+			</para></listitem>
+			<listitem><para>
+				<emphasis>rtname</emphasis> - the name of the route block to
+				execute. Can be a static string value or a dynamic string with
+				pseudo-variables.
+			</para></listitem>
+		</itemizedlist>
+		<para>
+		This function can be used in ANY_ROUTE.
+		</para>
+		<example>
+		<title><function>t_continue</function> usage</title>
+		<programlisting format="linespecific">
+...
+tcontinue('123', '456', 'MYROUTE');
+...
+</programlisting>
+		</example>
+	</section>
    </section>
<section>

    