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

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=733d8ca… Author: Richard Good &lt;richard.good(a)smilecoms.com&gt; Committer: Richard Good &lt;richard.good(a)smilecoms.com&gt; 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, &lt;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, &lt;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, &lt;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, &lt;0 - error.</para> + </section> </section> </section>