[sr-dev] git:tmp/tm_async_reply_support: modules/tm: Updated documentation to include t_suspend

[Richard Good]

Module: sip-router
Branch: tmp/tm_async_reply_support
Commit: 733d8ca38dd6fc4f931cd48cdb0bf8f7634857e7
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=733d8ca38dd6fc4f931cd48cdb0bf8f7634857e7

Author: Richard Good <richard.good at smilecoms.com>
Committer: Richard Good <richard.good at smilecoms.com>
Date:   Thu Jul  4 17:10:16 2013 +0200

modules/tm:  Updated documentation to include t_suspend
	- API documentation updated to include new methods:
	t_suspend_reply, t_continue_reply, t_cancel_suspend_reply

---

 modules/tm/doc/api.xml |  122 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 122 insertions(+), 0 deletions(-)

diff --git a/modules/tm/doc/api.xml b/modules/tm/doc/api.xml
index 2a627ab..7aeea5d 100644
--- a/modules/tm/doc/api.xml
+++ b/modules/tm/doc/api.xml
@@ -262,5 +262,127 @@ end of body
 	    </itemizedlist>
 	    <para>Return value: 0 - success, <0 - error.</para>
 	</section>
+        
+        <section id="t_suspend_reply">
+	    <title>
+	    	<function>int t_suspend_reply(struct sip_msg *msg,
+			unsigned int *hash_index, unsigned int *label)</function>
+	    </title>
+	    <para>
+	    	For programmatic use only.
+                This function is the equivalent of t_continue, but used to 
+                suspend on SIP responses.
+		This function together with t_continue_reply() can be used to
+		implement asynchronous actions on responses: t_suspend() saves 
+                the transaction, returns its identifiers, and t_continue() continues the
+		SIP response processing. (The response processing does not continue
+		from the same point in the script, a separate route block defined
+		by the parameter of t_continue_reply() is executed instead. The reply lock
+		is held during the route block execution.)
+		FR timer is ticking while the transaction is suspended, and the
+		transaction's failure route is executed if t_continue() is not
+		called in time.
+	    </para>
+	    <para>Meaning of the parameters is as follows:</para>
+	    <itemizedlist>
+		<listitem>
+		    <para><emphasis>msg</emphasis> - SIP message pointer.
+		    </para>
+		</listitem>
+		<listitem>
+		    <para><emphasis>hash_index</emphasis> - transaction identifier.
+		    </para>
+		</listitem>
+		<listitem>
+		    <para><emphasis>label</emphasis> - transaction identifier.
+		    </para>
+		</listitem>
+	    </itemizedlist>
+	    <para>Return value: 0 - success, <0 - error.</para>
+	    <para>
+		Usage: Allocate a memory block for storing the transaction identifiers
+		(hash_index and label), and for storing also any variable related to
+		the async query. Before calling t_suspend(), register for the following
+		callbacks, and pass the pointer to the allocated shared memory as
+		a parameter: TMCB_ON_FAILURE, TMCB_DESTROY, and TMCB_E2ECANCEL_IN
+		(in case of INVITE transaction). The async operation can be
+		cancelled, if it is still pending, when TMCB_ON_FAILURE or
+		TMCB_E2ECANCEL_IN is called. TMCB_DESTROY is suitable to free
+		the shared memory allocated for the async and SIP transaction identifiers.
+		Once the async query result is available call t_continue(), see below.
+		The SIP transaction must exist before calling t_suspend(), and the module
+		function calling t_suspend() should return 0 to make sure that the script
+		processing does not continue.
+	    </para>
+	</section>
+
+	<section id="t_continue_reply">
+	    <title>
+		<function>int t_continue_reply(unsigned int hash_index, unsigned int label,
+		                struct action *route, int branch)</function>
+	    </title>
+	    <para>
+		For programmatic use only.
+                This function is the equivalent of t_continue but used to 
+                suspend on SIP responses.
+		This function is the pair of t_suspend_reply(), and is supposed
+		to be called when the asynchronous query result is available.
+		The function executes a route block with the saved SIP message.
+                The calling application passes in the branch of the suspended 
+                reply when wanting to continue.
+	    </para>
+	    <para>Meaning of the parameters is as follows:</para>
+	    <itemizedlist>
+		<listitem>
+		    <para><emphasis>hash_index</emphasis> - transaction identifier.
+		    </para>
+		</listitem>
+		<listitem>
+		    <para><emphasis>label</emphasis> - transaction identifier.
+		    </para>
+		</listitem>
+		<listitem>
+		    <para><emphasis>route</emphasis> - route block to execute.
+		    </para>
+		</listitem>
+                <listitem>
+		    <para><emphasis>branch</emphasis> - reply branch to resume.
+		    </para>
+		</listitem>
+	    </itemizedlist>
+	    <para>Return value: 0 - success, <0 - error.</para>
+	</section>
+    
+	<section id="t_cancel_suspend_reply">
+	    <title>
+	    	<function>int t_cancel_suspend_reply(unsigned int hash_index, unsigned int label, branch)</function>
+	    </title>
+	    <para>
+	    	For programmatic use only.
+                This function is the equivalent of t_cancel_suspend but for SIP
+                responses.
+		This function is for revoking t_suspend_reply() from the
+		same process as it was executed before. t_cancel_suspend_reply() can be
+		used when something fails after t_suspend_reply() has already been executed
+		and it turns out that the transcation should not have been
+		suspended. The function cancels the FR timer of the transacation.
+	    </para>
+	    <para>Meaning of the parameters is as follows:</para>
+	    <itemizedlist>
+		<listitem>
+		    <para><emphasis>hash_index</emphasis> - transaction identifier.
+		    </para>
+		</listitem>
+		<listitem>
+		    <para><emphasis>label</emphasis> - transaction identifier.
+		    </para>
+		</listitem>
+                <listitem>
+		    <para><emphasis>branch</emphasis> - reply branch that was suspended.
+		    </para>
+                </listitem>
+	    </itemizedlist>
+	    <para>Return value: 0 - success, <0 - error.</para>
+	</section>
     </section>
 </section>