<?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>
		This module provides an HTTP transport layer implementation for
		the RPC management interface in a human-readable format.
	<para>
	</para>
		The xHTTP_RPC module uses the xHTTP module to handle HTTP requests.
		Read the documentation of the xHTTP module for more details.
	</para>

	<section>
	<title>Limitations</title>
	<itemizedlist>
	<listitem>
	<para>
		This module does not implement asynchronous RPC commands.
		It is unlikely that asynchronous RPC commands will be executed
		from an RPC web interface.
	</para>
	</listitem>
	<listitem>
	<para>
		This module does not accept parameters embedded in a structure
		(see RPC documentation for more info about how parameters can be
		passed to RPC).
	</para>
	</listitem>
	<listitem>
	<para>
		At startup, all RPC commands are sorted and grouped based on
		their format. The expected format is [group].[subcommand].
		The initial xhttp_rpc webpage displays all the retrieved groups.
		All RPC commands are available as sub-menus of each [group].
		If an RPC command is not in the expected format, it will be
		dropped from the initial xhttp_rpc home page menu.
	</para>
	</listitem>
	</itemizedlist>
	</section>
	</section>

	<section>
	<title>Dependencies</title>
	<section>
		<title>&kamailio; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>xhttp</emphasis> - xHTTP.
			</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>None</emphasis>
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	<section>
	<title>Parameters</title>
	<section>
		<title><varname>xhttp_rpc_root</varname> (str)</title>
		<para>
			Specifies the root path for RPC http requests.
			The link to the RPC web interface must be constructed
			using the following pattern:
			http://[server_IP]:[tcp_port]/[xhttp_rpc_root] 
		</para>
		<para>
		<emphasis>
			Default value is "rpc".
		</emphasis>
		</para>
		<example>
		<title>Set <varname>xhttp_rpc_root</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("xhttp_rpc", "xhttp_rpc_root", "http_rpc")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>xhttp_rpc_buf_size</varname> (str)</title>
		<para>
			Specifies the maximum length of the buffer (in bytes) used
			to write the RPC reply information in order to
			build the HTML response.
		</para>
		<para>
		<emphasis>
			Default value is 0 (auto set to 1/3 of the size of the configured pkg mem).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>xhttp_rpc_buf_size</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("xhttp", "xhttp_rpc_buf_size", 1024)
...
</programlisting>
		</example>
	</section>
	</section>

	<section>
	<title>Functions</title>
 	<section>
	    <title>
		<function moreinfo="none">dispatch_xhttp_rpc()</function>
	    </title>
	    <para>
		Handle the HTTP request and generate a response.
	    </para>
		<example>
		<title><function>dispatch_xhttp_rpc</function> usage</title>
		<programlisting format="linespecific">
...
tcp_accept_no_cl=yes
...
loadmodule "sl.so"
loadmodule "xhttp.so"
loadmodule "xhttp_rpc.so"
...
modparam("xhttp_rpc", "xhttp_rpc_root", "http_rpc")
...
event_route[xhttp:request] {
	$var(xhttp_rpc_root) = $(hu{s.substr,0,9});
	if ($var(xhttp_rpc_root) == "/http_rpc")
		dispatch_xhttp_rpc();
	else
		xhttp_reply("200", "OK", "text/html",
        		"&lt;html&gt;&lt;body&gt;Wrong URL $hu&lt;/body&gt;&lt;/html&gt;");
}
...
</programlisting>
	    </example>
	</section>
	</section>
</chapter>

