[SR-Dev] git:master: doc: xmlrpc functions and params added

Module: sip-router Branch: master Commit: a23b076fff03adc14dfb366b2827d304c43fb623 URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=a23b076… Author: Andrei Pelinescu-Onciul &lt;andrei(a)iptel.org&gt; Committer: Andrei Pelinescu-Onciul &lt;andrei(a)iptel.org&gt; 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>