[sr-dev] git:master: xmlrpc doc: use set_reply_close()

[Andrei Pelinescu-Onciul]

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

Author: Andrei Pelinescu-Onciul <andrei at iptel.org>
Committer: Andrei Pelinescu-Onciul <andrei at iptel.org>
Date:   Fri Sep 18 23:56:08 2009 +0200

xmlrpc doc: use set_reply_close()

Updated doc & examples to use set_reply_close() and
set_reply_no_connect() in the XMLRPC route instead of return -1.
(this allows using rpc async commands with the broken python
xmlrpclib).

---

 modules_s/xmlrpc/README            |   19 ++++++++++++++++---
 modules_s/xmlrpc/doc/functions.xml |    6 ++++++
 modules_s/xmlrpc/doc/xmlrpc.xml    |   14 +++++++++++---
 3 files changed, 33 insertions(+), 6 deletions(-)

diff --git a/modules_s/xmlrpc/README b/modules_s/xmlrpc/README
index b497e66..d1abb54 100644
--- a/modules_s/xmlrpc/README
+++ b/modules_s/xmlrpc/README
@@ -456,14 +456,21 @@ Content-Length: 276
    xmlrpclib with a Transport class that works.
 
    For the second solution (force closing tcp connections after answering)
-   the XMLRPC route should end with a return -1, exit -1 or drop -1.
+   the XMLRPC route should have a set_reply_close() command before
+   dispatch_rpc(). set_reply_no_connect() is also recommended (avoid
+   trying to open tcp connection to xmlrpc clients that closed it).
+   Alternatively ending the XMLRPC route with return -1, exit -1 or drop
+   -1 can also be used, but note that this will not work for async rpcs
+   (it will close the connection immeidately and not on the async
+   response).
 
    Example 1.
 route[XMLRPC]{
-        dispatch_rpc();
         # close connection only for xmlrpclib user agents
         if search("^User-Agent:.*xmlrpclib"))
-                return -1 ;
+                set_reply_close();
+        set_reply_no_connect(); # optional
+        dispatch_rpc();
 }
 
 1.4. Client Examples
@@ -543,6 +550,9 @@ modparam("xmlrpc", "autoconversion", 1)
 modparam("xmlrpc", "route", "XMLRPC");
 #...
 route[XMLRPC]{
+        if search("^User-Agent:.*xmlrpclib"))
+                set_reply_close();
+        set_reply_no_connect(); # optional
         dispatch_rpc();
 }
 
@@ -566,5 +576,8 @@ route[XMLRPC]{
                 xmlrpc_reply("400", "Unauthorized");
                 return;
         }
+        if search("^User-Agent:.*xmlrpclib"))
+                set_reply_close();
+        set_reply_no_connect(); # optional
         dispatch_rpc();
 }
diff --git a/modules_s/xmlrpc/doc/functions.xml b/modules_s/xmlrpc/doc/functions.xml
index bc3820f..adacbac 100644
--- a/modules_s/xmlrpc/doc/functions.xml
+++ b/modules_s/xmlrpc/doc/functions.xml
@@ -43,6 +43,9 @@
 modparam("xmlrpc", "route", "XMLRPC");
 #...
 route[XMLRPC]{
+	if search("^User-Agent:.*xmlrpclib"))
+		set_reply_close();
+	set_reply_no_connect(); # optional
 	dispatch_rpc();
 }
 		</programlisting>
@@ -74,6 +77,9 @@ route[XMLRPC]{
 		xmlrpc_reply("400", "Unauthorized");
 		return;
 	}
+	if search("^User-Agent:.*xmlrpclib"))
+		set_reply_close();
+	set_reply_no_connect(); # optional
 	dispatch_rpc();
 }
 		</programlisting>
diff --git a/modules_s/xmlrpc/doc/xmlrpc.xml b/modules_s/xmlrpc/doc/xmlrpc.xml
index c893e97..2cdf422 100644
--- a/modules_s/xmlrpc/doc/xmlrpc.xml
+++ b/modules_s/xmlrpc/doc/xmlrpc.xml
@@ -677,15 +677,23 @@ Content-Length: 276
 		</para>
 		<para>
 		For the second solution (force closing tcp connections after answering)
-		the XMLRPC route should end with a return -1, exit -1 or drop -1.
+		the XMLRPC route should have a <function>set_reply_close()</function>
+		command before <function>dispatch_rpc()</function>.
+		<function>set_reply_no_connect()</function> is also recommended
+		(avoid trying to open tcp connection to xmlrpc clients that closed it).
+		Alternatively ending the XMLRPC route with return -1, exit -1 or
+		drop -1 can also be used, but note that this will not work for 
+		async rpcs (it will close the connection immeidately and not on the
+		async response).
 		<example>
 		<programlisting>
 <![CDATA[
 route[XMLRPC]{
-	dispatch_rpc();
 	# close connection only for xmlrpclib user agents
 	if search("^User-Agent:.*xmlrpclib"))
-		return -1 ;
+		set_reply_close();
+	set_reply_no_connect(); # optional
+	dispatch_rpc();
 }
 ]]>
 		</programlisting>