[sr-dev] git:master: async: documented async_route() function

[Daniel-Constantin Mierla]

Module: sip-router
Branch: master
Commit: 31b97e44437d66aef098f553417c647025f323cc
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=31b97e44437d66aef098f553417c647025f323cc

Author: Daniel-Constantin Mierla <miconda at gmail.com>
Committer: Daniel-Constantin Mierla <miconda at gmail.com>
Date:   Sun Jun 26 11:42:01 2011 +0200

async: documented async_route() function

---

 modules/async/README              |   43 ++++++++++++++++++++++++++++++++----
 modules/async/doc/async_admin.xml |   42 +++++++++++++++++++++++++++++++++++-
 2 files changed, 79 insertions(+), 6 deletions(-)

diff --git a/modules/async/README b/modules/async/README
index c10a562..e01da48 100644
--- a/modules/async/README
+++ b/modules/async/README
@@ -29,12 +29,14 @@ Daniel-Constantin Mierla
 
         4. Exported Functions
 
-              4.1. async_sleep(seconds)
+              4.1. async_route(routename, seconds)
+              4.2. async_sleep(seconds)
 
    List of Examples
 
    1.1. Set workers parameter
    1.2. async_sleep usage
+   1.3. async_sleep usage
 
 Chapter 1. Admin Guide
 
@@ -52,7 +54,8 @@ Chapter 1. Admin Guide
 
    4. Exported Functions
 
-        4.1. async_sleep(seconds)
+        4.1. async_route(routename, seconds)
+        4.2. async_sleep(seconds)
 
 1. Overview
 
@@ -101,9 +104,39 @@ modparam("async", "workers", 2)
 
 4. Exported Functions
 
-   4.1. async_sleep(seconds)
+   4.1. async_route(routename, seconds)
+   4.2. async_sleep(seconds)
 
-4.1. async_sleep(seconds)
+4.1. async_route(routename, seconds)
+
+   Simulate a sleep of 'seconds' and then continue the processing of SIP
+   request with the route[routename]. In case of internal errors, the
+   function returns false, otherwise the function exits the execution of
+   config at that moment (return 0 behaviour).
+
+   The routename parameter can be a static string or a dynamic string
+   value with config variables.
+
+   The sleep parameter represent the number of seconds to suppend the
+   processing of SIP request. Maximum value is 100. The parameter can be a
+   static integer or a varaible holding an integer.
+
+   Since the SIP request handling is resumed in another process,
+   practically the config file execution state is lost. Therefore beware
+   that the execution of config after resume will end once the
+   route[routename] is finished.
+
+   Example 1.2. async_sleep usage
+...
+async_route("RESUME", "4");
+...
+route[RESUME] {
+   send_reply("404", "Not found");
+   exit;
+}
+...
+
+4.2. async_sleep(seconds)
 
    Simulate a sleep of 'seconds' and then continue the processing of SIP
    request with the next action. In case of internal errors, the function
@@ -119,7 +152,7 @@ modparam("async", "workers", 2)
    that the execution of config after resume will end once the route block
    where async_sleep() is called is finished.
 
-   Example 1.2. async_sleep usage
+   Example 1.3. async_sleep usage
 ...
 async_sleep("4");
 send_reply("404", "Not found");
diff --git a/modules/async/doc/async_admin.xml b/modules/async/doc/async_admin.xml
index 2506f06..3fbaeab 100644
--- a/modules/async/doc/async_admin.xml
+++ b/modules/async/doc/async_admin.xml
@@ -87,7 +87,47 @@ modparam("async", "workers", 2)
 
 	<section>
 	<title>Exported Functions</title>
- 	<section>
+	<section>
+	    <title>
+		<function moreinfo="none">async_route(routename, seconds)</function>
+	    </title>
+	    <para>
+		Simulate a sleep of 'seconds' and then continue the processing of SIP
+		request with the route[routename]. In case of internal errors, the
+		function returns false, otherwise the function exits the execution of
+		config at that moment (return 0 behaviour).
+		</para>
+		<para>
+		The routename parameter can be a static string or a dynamic string
+		value with config variables.
+		</para>
+		<para>
+		The sleep parameter represent the number of seconds to suppend the
+		processing of SIP request. Maximum value is 100. The parameter can be
+		a static integer or a varaible holding an integer.
+		</para>
+		<para>
+		Since the SIP request handling is resumed in another process,
+		practically the config file execution state is lost. Therefore beware
+		that the execution of config after resume will end once the
+		route[routename] is finished.
+		</para>
+		<example>
+		<title><function>async_sleep</function> usage</title>
+		<programlisting format="linespecific">
+...
+async_route("RESUME", "4");
+...
+route[RESUME] {
+   send_reply("404", "Not found");
+   exit;
+}
+...
+</programlisting>
+	    </example>
+	</section>
+
+	<section>
 	    <title>
 		<function moreinfo="none">async_sleep(seconds)</function>
 	    </title>