<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
%docentities;

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

<chapter>
	
	<title>&adminguide;</title>
	
	<section>
	<title>Overview</title>
	<para>
		NOTE: this module depends on specific versions of libxmlrpc-c3, which may
		not be available on your OS. You better use the 'xmlrpc' module located in
		'modules/' folder. It can run any MI command by loading 'mi_rpc' module and
		executing RPC command 'mi', with first parameter being the MI command,
		then followed by other parameters that will be passed to the MI command.
	</para>
	<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>	
	<para>
		Implementation of mi_xmlrpc module's xmlrpc server is based on Abyss
		XML-RPC server.  Current version of Abyss server
		"normalizes" CRLF sequence in received XML-RPC strings
		to LF character, which makes it impossible to pass CRLF
		sequence from xmlrpc client application to &kamailio; modules,
		such as mi_fifo and pua_mi, that accept requests via MI
		transport.  To overcome this limitation mi_xmlrpc module
		implements a hack that coverts each LFLF sequence in
	        received XML-RPC strings to CRLF sequence.
	</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>&kamailio; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>No dependencies on other &kamailio; 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 &kamailio; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>libxml</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>libxmlrpc-c3</emphasis> version 0.9.10 or version 1.06.[10-30].
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>libxmlrpc-c3-dev</emphasis> version 0.9.10 or version 1.06.[10-30].
			</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.
		</para>
	</section>
	</section>
	
	<section>
	<title>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>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>

