[sr-dev] git:tmp/tm_async_reply_support: modules/tm/doc: Updated documentation for TM with merged methods

Module: sip-router Branch: tmp/tm_async_reply_support Commit: 8885e218ef4c187b22183bf67adfb7c60407c478 URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=8885e21… Author: Richard Good &lt;richard.good(a)smilecoms.com&gt; Committer: Richard Good &lt;richard.good(a)smilecoms.com&gt; Date: Tue Jul 16 16:05:32 2013 +0200 modules/tm/doc: Updated documentation for TM with merged methods --- modules/tm/doc/api.xml | 124 +----------------------------------------------- 1 files changed, 1 insertions(+), 123 deletions(-) diff --git a/modules/tm/doc/api.xml b/modules/tm/doc/api.xml index 7aeea5d..0a3c751 100644 --- a/modules/tm/doc/api.xml +++ b/modules/tm/doc/api.xml @@ -157,7 +157,7 @@ end of body This function together with t_continue() can be used to implement asynchronous actions: t_suspend() saves the transaction, returns its identifiers, and t_continue() continues the - SIP request processing. (The request processing does not continue + SIP request/response processing. (The request/response processing does not continue from the same point in the script, a separate route block defined by the parameter of t_continue() is executed instead. The reply lock is held during the route block execution.) @@ -262,127 +262,5 @@ 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>