Browse code

doc: xmlrpc functions and params added

Andrei Pelinescu-Onciul authored on 11/05/2009 14:50:15
Showing 3 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,84 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3
+	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
+
5
+<section id="xmlrpc.functions" xmlns:xi="http://www.w3.org/2001/XInclude">
6
+	<sectioninfo>
7
+	<revhistory>
8
+		<revision>
9
+		<revnumber>$Revision$</revnumber>
10
+		<date>$Date$</date>
11
+		</revision>
12
+	</revhistory>
13
+	</sectioninfo>
14
+
15
+	<title>Functions</title>
16
+
17
+	<section id="xmlrpc.dispatch_rpc">
18
+	<title>
19
+		<function>dispatch_rpc()</function>
20
+	</title>
21
+	<para>
22
+		This function processes an XMLRPC request, found in the body of
23
+		the request.
24
+	</para>
25
+	<para>
26
+		It should be used only in a route specified using the
27
+		<varname>"route"</varname> module parameter or if the request method
28
+		is GET or POST (using it for other request methods will not have
29
+		adverse side-effects, but it will probably not work).
30
+	</para>
31
+	<para>
32
+		dispatch_rpc() extracts the XML-RPC document from the body of the
33
+		request to determine the name of the RPC method to be called and then
34
+		it searches through the list of all the RPC functions to find a
35
+		function with matching name. If such a function is found then
36
+		dispatch_rpc() will pass control to the function to handle the
37
+		request.
38
+	</para>
39
+	<example>
40
+		<title><function>dispatch_rpc</function> usage</title>
41
+		<programlisting>
42
+#...
43
+modparam("xmlrpc", "route", "XMLRPC");
44
+#...
45
+route[XMLRPC]{
46
+	dispatch_rpc();
47
+}
48
+		</programlisting>
49
+	</example>
50
+	</section>
51
+
52
+	<section id="xmlrpc.xmlrpc_reply">
53
+	<title>
54
+		<function>xmlrpc_reply(code, reason)</function>
55
+	</title>
56
+	<para>
57
+		This function can be called from the config script to directly
58
+		generate an XML-RPC reply.
59
+	</para>
60
+	<example>
61
+		<title><function>xmlrpc_reply</function> usage</title>
62
+		<programlisting>
63
+#...
64
+modparam("xmlrpc", "route", "XMLRPC");
65
+#...
66
+route[XMLRPC]{
67
+	# allow XMLRPC requests only on TLS and only if the client
68
+	# certificate is valid
69
+	if (proto!=TLS){
70
+		xmlrpc_reply("400", "xmlrpc allowed only over TLS");
71
+		return;
72
+	}
73
+	if (@tls.peer.verified!=""){
74
+		xmlrpc_reply("400", "Unauthorized");
75
+		return;
76
+	}
77
+	dispatch_rpc();
78
+}
79
+		</programlisting>
80
+	</example>
81
+	</section>
82
+
83
+
84
+</section>
0 85
new file mode 100644
... ...
@@ -0,0 +1,67 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
3
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
+
5
+<section id="xmlrpc.parameters" xmlns:xi="http://www.w3.org/2001/XInclude">
6
+	<sectioninfo>
7
+	<revhistory>
8
+		<revision>
9
+		<revnumber>$Revision$</revnumber>
10
+		<date>$Date$</date>
11
+		</revision>
12
+	</revhistory>
13
+	</sectioninfo>
14
+
15
+	<title>Parameters</title>
16
+
17
+	<section id="route">
18
+	<title><varname>route</varname> (string)</title>
19
+	<para>
20
+		Name of the route called for XMLRPC messages.
21
+	</para>
22
+	<para>
23
+		This route will be called only for HTTP messages whose method is
24
+		either GET or POST. The message visible inside the route
25
+		will be a HTTP request converted to SIP (the uri will be fixed and
26
+		a fake via will be added).
27
+	</para>
28
+	<para>
29
+		The route should perform additional security checks to
30
+		ensure the client is authorized to execute management/RPC functions
31
+		and then it should call the <function>dispatch_rpc()</function>.
32
+	</para>
33
+	<para>
34
+		Default: the main route is used.
35
+	</para>
36
+	<example>
37
+		<title>Set <varname>route</varname> parameter</title>
38
+		<programlisting>
39
+modparam("xmlrpc", "route", "route_for_xmlrpcs")
40
+		</programlisting>
41
+	</example>
42
+	</section>
43
+
44
+	<!--
45
+	Seems to be obsolete (on always) -andrei
46
+	<section id="enable_introspection">
47
+	<title><varname>enable_introspection</varname> (integer)</title>
48
+	<para>
49
+		Enable/disable additional introspection methods. If set to 1 then
50
+		the functions defined in
51
+		http://scripts.incutio.com/xmlrpc/introspection.html
52
+		will be available on the server. If set to 0 then the functions will 
53
+		be disabled.
54
+	</para>
55
+	<para>
56
+		Default: 1 (enabled).
57
+	</para>
58
+	<example>
59
+		<title>Set <varname>enable_introspection</varname> parameter</title>
60
+		<programlisting>
61
+modparam("xmlrpc", "enable_introspection", 0)
62
+		</programlisting>
63
+	</example>
64
+	</section>
65
+	-->
66
+
67
+</section>
... ...
@@ -686,4 +686,7 @@ Content-Length: 276
686 686
 	</para>
687 687
     </section>
688 688
 
689
+	<xi:include href="params.xml"/>
690
+	<xi:include href="functions.xml"/>
691
+
689 692
 </section>