[sr-dev] git:master: xmlrpc(s): doc updated

Andrei Pelinescu-Onciul andrei at iptel.org
Wed Sep 23 16:19:37 CEST 2009 

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

Author: Andrei Pelinescu-Onciul <andrei at iptel.org>
Committer: Andrei Pelinescu-Onciul <andrei at iptel.org>
Date:   Wed Sep 23 16:19:11 2009 +0200

xmlrpc(s): doc updated

- escape_cr and double_lf_to_crlf documented

---

 modules_s/xmlrpc/README         |   45 ++++++++++++++++++++++++++++++++++-
 modules_s/xmlrpc/doc/params.xml |   49 +++++++++++++++++++++++++++++++++++++++
 modules_s/xmlrpc/doc/xmlrpc.xml |   10 ++++++++
 3 files changed, 102 insertions(+), 2 deletions(-)

diff --git a/modules_s/xmlrpc/README b/modules_s/xmlrpc/README
index d1abb54..fed4a70 100644
--- a/modules_s/xmlrpc/README
+++ b/modules_s/xmlrpc/README
@@ -22,6 +22,8 @@ Jan Janak
 
         1.5.1. route (string)
         1.5.2. autoconversion (string)
+        1.5.3. escape_cr (integer)
+        1.5.4. double_lf_to_crlf (integer)
 
    1.6. Functions
 
@@ -473,6 +475,14 @@ route[XMLRPC]{
         dispatch_rpc();
 }
 
+   Another common problem is CRLF handling. According to the xml spec CR
+   ('\r') must be escaped (to &#xD;) or they will be "normalized" when
+   parsing the xml document. However some xmlrpc clients do not follow
+   this rule (e.g. clients based on the python or php xmlrpclib) and send
+   CRLF unescaped. A possible workaround is to enable automatic LFLF to
+   CRLF conversion (using the double_lf_to_crlf modules parameter) and
+   replace CRLF with LFLF in the client queries.
+
 1.4. Client Examples
 
      * examples/xmlrpc_test.pl (basic perl application that builds and
@@ -524,6 +534,37 @@ modparam("xmlrpc", "route", "route_for_xmlrpcs")
    Example 3. Set the autoconversion parameter
 modparam("xmlrpc", "autoconversion", 1)
 
+1.5.3. escape_cr (integer)
+
+   Enable CR ('\r') escaping in replies. If enabled each '\r' in the
+   xmlrpc reply will be replaced with "&#xD;", according to the xml spec.
+
+   It should be turned off only if you suspect interoperability problems
+   with older clients.
+
+   Default: on.
+
+   Example 4. Set the escape_cr parameter
+modparam("xmlrpc", "escape_cr", 1)
+
+1.5.4. double_lf_to_crlf (integer)
+
+   When enabled double LFs ('\n\n') in the input xmlrpc strings will be
+   replaced with CR LF ('\r\n'). This makes LF LF behave like an escape
+   character for CR LF and is needed for compatibility with kamailio tools
+   and to work around buggy xmlrpc clients that don't escape the CR in CR
+   LF ('\r' should be escaped to "&#xD;" otherwise according to the xml
+   spec "\r\n" will be transformed to '\n'), but need to send CR LF in the
+   strings (e.g. they use tm.t_uac_wait).
+
+   Note: when this option is turned on, there is no way to send a double
+   LF ('\n\n'), it will always be transformed in CR LF ('\r\n').
+
+   Default: off.
+
+   Example 5. Set the double_lf_to_crlf parameter
+modparam("xmlrpc", "double_lf_to_crlf", 1)
+
 1.6. Functions
 
    Revision History
@@ -545,7 +586,7 @@ modparam("xmlrpc", "autoconversion", 1)
    function with matching name. If such a function is found then
    dispatch_rpc() will pass control to the function to handle the request.
 
-   Example 4. dispatch_rpc usage
+   Example 6. dispatch_rpc usage
 #...
 modparam("xmlrpc", "route", "XMLRPC");
 #...
@@ -561,7 +602,7 @@ route[XMLRPC]{
    This function can be called from the config script to directly generate
    an XML-RPC reply.
 
-   Example 5. xmlrpc_reply usage
+   Example 7. xmlrpc_reply usage
 #...
 modparam("xmlrpc", "route", "XMLRPC");
 #...
diff --git a/modules_s/xmlrpc/doc/params.xml b/modules_s/xmlrpc/doc/params.xml
index be7fd63..f200b55 100644
--- a/modules_s/xmlrpc/doc/params.xml
+++ b/modules_s/xmlrpc/doc/params.xml
@@ -67,6 +67,55 @@ modparam("xmlrpc", "autoconversion", 1)
 	</example>
 	</section>
 
+	<section id="escape_cr">
+	<title><varname>escape_cr</varname> (integer)</title>
+	<para>
+		Enable CR ('\r') escaping in replies. If enabled each '\r' in the
+		xmlrpc reply will be replaced with "&amp;#xD;", according to the
+		xml spec.
+	</para>
+	<para>
+		It should be turned off only if you suspect interoperability problems
+		with older clients.
+	</para>
+	<para>
+		Default: on.
+	</para>
+	<example>
+		<title>Set the <varname>escape_cr</varname> parameter</title>
+		<programlisting>
+modparam("xmlrpc", "escape_cr", 1)
+		</programlisting>
+	</example>
+	</section>
+
+	<section id="double_lf_to_crlf">
+	<title><varname>double_lf_to_crlf</varname> (integer)</title>
+	<para>
+		When enabled double LFs ('\n\n') in the input xmlrpc strings
+		will be replaced with CR LF ('\r\n'). This makes LF LF behave like
+		an escape character for CR LF and is needed for compatibility with
+		kamailio tools and to work around buggy xmlrpc clients that don't
+		escape the CR in CR LF ('\r' should be escaped to "&amp;#xD;"
+		otherwise according to the xml spec "\r\n" will be transformed to
+		'\n'), but need to send CR LF in the strings (e.g. they use
+		<function>tm.t_uac_wait</function>).
+	</para>
+	<para>
+		Note: when this option is turned on, there is no way to send a double
+		LF ('\n\n'), it will always be transformed in CR LF ('\r\n').
+	</para>
+	<para>
+		Default: off.
+	</para>
+	<example>
+		<title>Set the <varname>double_lf_to_crlf</varname> parameter</title>
+		<programlisting>
+modparam("xmlrpc", "double_lf_to_crlf", 1)
+		</programlisting>
+	</example>
+	</section>
+
 	<!--
 	Obsolete (hardwired on in the rpc core functions, cannot  be turned off) 
 	-andrei
diff --git a/modules_s/xmlrpc/doc/xmlrpc.xml b/modules_s/xmlrpc/doc/xmlrpc.xml
index 2cdf422..81cf02a 100644
--- a/modules_s/xmlrpc/doc/xmlrpc.xml
+++ b/modules_s/xmlrpc/doc/xmlrpc.xml
@@ -699,6 +699,16 @@ route[XMLRPC]{
 		</programlisting>
 		</example>
 		</para>
+	    <para>
+		Another common problem is CRLF handling. According to the xml spec
+		CR ('\r') must be escaped (to &amp;#xD;) or they will be "normalized"
+		when parsing the xml document. However some xmlrpc clients do not
+		follow this rule (e.g. clients based on the python or php xmlrpclib)
+		and send CRLF unescaped. A possible workaround is to enable
+		automatic LFLF to CRLF conversion (using the
+		<varname>double_lf_to_crlf</varname> modules parameter) and replace
+		CRLF with LFLF in the client queries.
+		</para>
 	</section>
     </section>

More information about the sr-dev mailing list