git:master: doc: xmlrpc functions and params added - sr-dev

11 May 2009

Module: sip-router
Branch: master
Commit: a23b076fff03adc14dfb366b2827d304c43fb623
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=a23b076f...
Author: Andrei Pelinescu-Onciul andrei@iptel.org
Committer: Andrei Pelinescu-Onciul andrei@iptel.org
Date:   Mon May 11 16:50:15 2009 +0200
doc: xmlrpc functions and params added
---
modules_s/xmlrpc/doc/functions.xml |   84 ++++++++++++++++++++++++++++++++++++
 modules_s/xmlrpc/doc/params.xml    |   67 ++++++++++++++++++++++++++++
 modules_s/xmlrpc/doc/xmlrpc.xml    |    3 +
 3 files changed, 154 insertions(+), 0 deletions(-)

diff --git a/modules_s/xmlrpc/doc/functions.xml b/modules_s/xmlrpc/doc/functions.xml
new file mode 100644
index 0000000..bc3820f
--- /dev/null
+++ b/modules_s/xmlrpc/doc/functions.xml
@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<section id="xmlrpc.functions" xmlns:xi="http://www.w3.org/2001/XInclude">
+	<sectioninfo>
+	<revhistory>
+		<revision>
+		<revnumber>$Revision$</revnumber>
+		<date>$Date$</date>
+		</revision>
+	</revhistory>
+	</sectioninfo>
+
+	<title>Functions</title>
+
+	<section id="xmlrpc.dispatch_rpc">
+	<title>
+		<function>dispatch_rpc()</function>
+	</title>
+	<para>
+		This function processes an XMLRPC request, found in the body of
+		the request.
+	</para>
+	<para>
+		It should be used only in a route specified using the
+		<varname>"route"</varname> module parameter or if the request method
+		is GET or POST (using it for other request methods will not have
+		adverse side-effects, but it will probably not work).
+	</para>
+	<para>
+		dispatch_rpc() extracts the XML-RPC document from the body of the
+		request to determine the name of the RPC method to be called and then
+		it searches through the list of all the RPC functions to find a
+		function with matching name. If such a function is found then
+		dispatch_rpc() will pass control to the function to handle the
+		request.
+	</para>
+	<example>
+		<title><function>dispatch_rpc</function> usage</title>
+		<programlisting>
+#...
+modparam("xmlrpc", "route", "XMLRPC");
+#...
+route[XMLRPC]{
+	dispatch_rpc();
+}
+		</programlisting>
+	</example>
+	</section>
+
+	<section id="xmlrpc.xmlrpc_reply">
+	<title>
+		<function>xmlrpc_reply(code, reason)</function>
+	</title>
+	<para>
+		This function can be called from the config script to directly
+		generate an XML-RPC reply.
+	</para>
+	<example>
+		<title><function>xmlrpc_reply</function> usage</title>
+		<programlisting>
+#...
+modparam("xmlrpc", "route", "XMLRPC");
+#...
+route[XMLRPC]{
+	# allow XMLRPC requests only on TLS and only if the client
+	# certificate is valid
+	if (proto!=TLS){
+		xmlrpc_reply("400", "xmlrpc allowed only over TLS");
+		return;
+	}
+	if (@tls.peer.verified!=""){
+		xmlrpc_reply("400", "Unauthorized");
+		return;
+	}
+	dispatch_rpc();
+}
+		</programlisting>
+	</example>
+	</section>
+
+
+</section>
diff --git a/modules_s/xmlrpc/doc/params.xml b/modules_s/xmlrpc/doc/params.xml
new file mode 100644
index 0000000..324495d
--- /dev/null
+++ b/modules_s/xmlrpc/doc/params.xml
@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<section id="xmlrpc.parameters" xmlns:xi="http://www.w3.org/2001/XInclude">
+	<sectioninfo>
+	<revhistory>
+		<revision>
+		<revnumber>$Revision$</revnumber>
+		<date>$Date$</date>
+		</revision>
+	</revhistory>
+	</sectioninfo>
+
+	<title>Parameters</title>
+
+	<section id="route">
+	<title><varname>route</varname> (string)</title>
+	<para>
+		Name of the route called for XMLRPC messages.
+	</para>
+	<para>
+		This route will be called only for HTTP messages whose method is
+		either GET or POST. The message visible inside the route
+		will be a HTTP request converted to SIP (the uri will be fixed and
+		a fake via will be added).
+	</para>
+	<para>
+		The route should perform additional security checks to
+		ensure the client is authorized to execute management/RPC functions
+		and then it should call the <function>dispatch_rpc()</function>.
+	</para>
+	<para>
+		Default: the main route is used.
+	</para>
+	<example>
+		<title>Set <varname>route</varname> parameter</title>
+		<programlisting>
+modparam("xmlrpc", "route", "route_for_xmlrpcs")
+		</programlisting>
+	</example>
+	</section>
+
+	<!--
+	Seems to be obsolete (on always) -andrei
+	<section id="enable_introspection">
+	<title><varname>enable_introspection</varname> (integer)</title>
+	<para>
+		Enable/disable additional introspection methods. If set to 1 then
+		the functions defined in
+		http://scripts.incutio.com/xmlrpc/introspection.html
+		will be available on the server. If set to 0 then the functions will 
+		be disabled.
+	</para>
+	<para>
+		Default: 1 (enabled).
+	</para>
+	<example>
+		<title>Set <varname>enable_introspection</varname> parameter</title>
+		<programlisting>
+modparam("xmlrpc", "enable_introspection", 0)
+		</programlisting>
+	</example>
+	</section>
+	-->
+
+</section>
diff --git a/modules_s/xmlrpc/doc/xmlrpc.xml b/modules_s/xmlrpc/doc/xmlrpc.xml
index 7a1b908..4438185 100644
--- a/modules_s/xmlrpc/doc/xmlrpc.xml
+++ b/modules_s/xmlrpc/doc/xmlrpc.xml
@@ -686,4 +686,7 @@ Content-Length: 276
    </para>
     </section>
+	<xi:include href="params.xml"/>
+	<xi:include href="functions.xml"/>
+
 </section>

    