<!-- Module User's Guide -->

<chapter>
	<chapterinfo>
	<revhistory>
		<revision>
		<revnumber>$Revision: 1827 $</revnumber>
		<date>$Date: 2007-03-12 17:22:53 +0200 (Mon, 12 Mar 2007) $</date>
		</revision>
	</revhistory>
	</chapterinfo>
	<title>User's Guide</title>
	
	<section>
	<title>Overview</title>
	<para>
		This module implements a xmlrpc server that handles xmlrpc requests and
		generates xmlrpc responses. When a xmlrpc message is received a default 
		method is executed.
	</para>
	<para>
		At first, it looks up the MI command. If found it parses the called 
		procedure's parameters into a MI tree and the command is executed. A 
		MI reply tree is returned that is formatted back in xmlrpc. The 
		response is built in two ways - like a string that contains the MI 
		tree nodes information (name, values and attributes) or like an array 
		whose elements are consisted of each MI tree node stored information.
	</para>	
	</section>

	<section>
	<title>To-do</title>
		<para>
		Features to be added in the future:
		</para>
		<itemizedlist>
			<listitem><para>
			possibility to select the listening IP address
			</para></listitem>
			<listitem><para>
			multiple ports per IP address
			</para></listitem>
		</itemizedlist>
	</section>
	
	<section>
	<title>Dependencies</title>
	<section>
		<title>&ser; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>No dependencies on other &ser; modules</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>

	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before 
		running &ser; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>libxml</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>libxmlrpc-c3</emphasis> version 0.9.10.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>libxmlrpc-c3-dev</emphasis> version 0.9.10.
			</para>
			</listitem>
			</itemizedlist>
		</para>
		<para>
		If libxmlrpc-c3[-dev] package is not available on your system, you may
		check if packages for your OS are not available on the 
		<quote>xmlrpc-c</quote>project 
		(<ulink url='http://xmlrpc-c.sourceforge.net/'>
		http://xmlrpc-c.sourceforge.net/</ulink>). Otherwise you need
		to install the library and devel headers from the sources. In both
		cases, keep in mind to use the 0.9.10 version!!.
		</para>
	</section>
	</section>
	
	<section>
	<title>Exported Parameters</title>
	<section>
		<title><varname>port</varname>(integer)</title>
		<para>
		The port number used by the XMLRPX server to listen for incoming 
		requests.
		</para>
		<para>
		<emphasis>The default value is 8080.</emphasis>
		Ports lower than 1024 are not accepted.
		</para>
		<example>
		<title>Set <varname>port</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mi_xmlrpc", "port", 8000)
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>log_file</varname>(string)</title>
		<para>
		A log file to be used by the internal Abyss html server used by the 
		XMLRPX library.
		</para>
		<para>
		<emphasis>The default values NONE (no logging).</emphasis>
		</para>
		<example>
		<title>Set <varname>log_file</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mi_xmlrpc", "log_file", "/var/log/abyss.log")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>reply_option</varname> (integer)</title>
		<para>
		Given the xmlrpc response specifications that a methodResponse can 
		contain a single params section with a single param section, there is 
		the possibility to choose between a string built response or an 
		array built one.
		</para>
		<para>
		For a 0 value, a single string parameter will be replied (merging the 
		whole response). For non-0 value, each line from the response will be 
		encoded as an element into an array of strings.
		</para>
		<para>
		<emphasis>The default option is a string built response (0).</emphasis>
		</para>
		<example>
		<title>Set <varname>reply_option</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mi_xmlrpc", "reply_option", 0)
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>buffer_size</varname> (integer)</title>
		<para>
		It specifies the maximum length of the buffer used to write in the MI 
		tree node information in order to build the xmlrpc response.
		</para>
		<para>
		<emphasis> The default value is 8192.</emphasis>
		</para>
		<example>
		<title>Set <varname>reply_option</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mi_xmlrpc", "buffer_size", 8192)
...
</programlisting>
		</example>
	</section>
	</section>

	<section>
	<title>Exported Functions</title>
		<para>
		No function exported to be used from configuration file.
		</para>
	</section>

	<section>
	<title>Example</title>
		<para>
		This is an example showing the xmlrpc format for the 
		<quote>get_statistics dialog: tm:</quote> MI commad:
		response.
		</para>
		<example>
		<title>XMLRPC request</title>
		<programlisting format="linespecific">
<![CDATA[

POST /RPC2 HTTP/1.0
Host: 127.0.0.1
Connection: close
User-Agent: OpenSIPg XML_RPC Client
Content-Type: text/xml
Content-Length: 1000

<?xml version="1.0" ?>
<methodCall>
   <methodName>get_statistics</methodName>
   <params>
       <param>
           <value><string>dialog:</string></value>
       </param>
       <param>
           <value><string>tm:</string></value>
       </param>
  </params>
</methodCall>

]]>
</programlisting>
		</example>

	</section>


</chapter>

<!-- Keep this element at the end of the file
Local Variables:
sgml-parent-document: ("mi_xmlrpc.sgml" "Book" "chapter")
End:
-->

