<?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 a web provisioning interface
		for &kamailio;.  It is using the &kamailio;'s internal
		database API to provide a simple way of manipulating
		records inside &kamailio;'s tables.
	</para>
	<para>
		The module offers:
		<itemizedlist>
			<listitem><para>
			ability to connect to multiple/different databases
			through &kamailio;'s db API;
			(all &kamailio;'s databases are supported);
			</para></listitem>
			<listitem><para>
			ability to perform data input validation through &kamailio; API;
			</para></listitem>
			<listitem><para>
			ability to reconfigure the interface layout on the fly by
			reloading the config from the xml framework via the rpc
			command interface.
			</para></listitem>
		</itemizedlist>
	</para>
	<para>
		Note: when provisioning tables using <emphasis>db_text</emphasis>,
		any change made to a <emphasis>db_text</emphasis> table will not
		be reflected on the actual text file.  In order to force a write
		out to the disk of the cached tables, the db_text rpc command
		<emphasis>db_text.dump</emphasis> must be used.
	</para>
	</section>

	<section>
	<title>Usage</title>
	<para>
		The layout of the provisionning interface is controlled via an external
		xml file (see the framework parameter).
		An example of a framework xml file is provided inside the &kamailio;'s
		examples directory.
		A simple framework file can be generated by the kamdbctl command:
		<programlisting format="linespecific">
kamdbctl pframework create
		</programlisting>
		The generated framework will be saved inside &kamailio;'s
		config directory as <emphasis>pi_framework_sample</emphasis>.
		The list of configurable tables will be based on the
		<emphasis>STANDARD_MODULES</emphasis> and
		<emphasis>EXTRA_MODULES</emphasis> vars from
		<emphasis>kamctlrc</emphasis> file.
		The sample framework file will provide the ability to inspect tables.
		In order to add/modify/remove records to/from tables,
		new commands must be added by the admin.
	</para>
	</section>

	<section>
	<title>Framework </title>
	<para>
		The xml framework file is organized in three distinctive blocks:
		<itemizedlist>
			<listitem><para>
			database connection definition block
			</para></listitem>
			<listitem><para>
			table definition block
			</para></listitem>
			<listitem><para>
			command definition block
			</para></listitem>
		</itemizedlist>
	</para>
	<section>
	<title>Database connection definition block</title>
	<para>
		Each connection to a particular database must be defined here
		with a unique database connection id.
		The connection parameters are defined following the db_url param pattern
		for all &kamailio; modules that are using a database.
	</para>
	<para>
		Supported databases:
		<itemizedlist>
			<listitem><para>berkeley</para></listitem>
			<listitem><para>cassandra</para></listitem>
			<listitem><para>cluster</para></listitem>
			<listitem><para>flatstore</para></listitem>
			<listitem><para>mysql</para></listitem>
			<listitem><para>oracle</para></listitem>
			<listitem><para>postgres</para></listitem>
			<listitem><para>sqlite</para></listitem>
			<listitem><para>text</para></listitem>
			<listitem><para>unixodbc</para></listitem>
		</itemizedlist>
	</para>
	</section>
	<section>
	<title>Table definition block</title>
	<para>
		Each table managed through the  &kamailio; provisioning interface
		must be defined here with a unique table id.
		For each table, the database connection id must be specified.
		Each table must list all columns that will be managed by the
		&kamailio; provisioning interface.
		Each column must have a unique field name and a type.
		Each column may have a validation tag for validating input data.
	</para>
	<para>
		Supported column types:
		<itemizedlist>
			<listitem><para>DB1_INT</para></listitem>
			<listitem><para>DB1_BIGINT</para></listitem>
			<listitem><para>DB1_DOUBLE</para></listitem>
			<listitem><para>DB1_STRING</para></listitem>
			<listitem><para>DB1_STR</para></listitem>
			<listitem><para>DB1_DATETIME</para>
			<itemizedlist>
				<listitem><para>Note: input field must be provided in
					'YEAR-MM-DD HH:MM:SS' format.</para>
				</listitem>
			</itemizedlist>
			</listitem>
			<listitem><para>DB1_BLOB</para></listitem>
			<listitem><para>DB1_BITMAP</para></listitem>
		</itemizedlist>
	</para>
	<para>
		Supported validation methods:
		<itemizedlist>
			<listitem><para>
			IPV4 - represents an IPv4 address
			</para></listitem>
			<listitem><para>
			URI - represents a SIP URI
			</para></listitem>
			<listitem><para>
			URI_IPV4HOST - represents a SIP URI with an IPV4 as a host
			</para></listitem>
			<listitem><para>
			P_HOST_PORT - represents [proto:]host[:port]
			</para></listitem>
			<listitem><para>
			P_IPV4_PORT - represents [proto:]IPv4[:port]
			</para></listitem>
		</itemizedlist>
	</para>
	</section>
	<section>
	<title>Command definition block</title>
	<para>
		Multiple provisioning commands can be grouped together.
		Each group can have multiple commands.
		Each command definition in a group must have the table id
		of the table that is operating on along with the command
		type to be performed.
	</para>
	<para>
		The command type can have up to three type of column parameters:
		<itemizedlist>
			<listitem><para>clause columns</para></listitem>
			<listitem><para>query columns</para></listitem>
			<listitem><para>order by columns</para></listitem>
		</itemizedlist>
		Each column parameter must define the name(s) of the column(s)
		(must match a field name in the description table identified
		by the table id).
		A column can accept a list of imposed values.
		Each imposed value will have an id that will be displayed
		on the web interface and the actual value that will be
		used for db operations.
		Clause columns must define operators.
		Here's the list of supported operators:
		'&lt;', '&gt;', '=', '&lt;=', '&gt;=', '!='.
	</para>
	<para>
		Supported database command types:
		<itemizedlist>
			<listitem><para>DB1_QUERY - performs an SQL query
			and supports three type of columns:</para>
			<itemizedlist>
				<listitem><para>clause: 0 or more columns</para></listitem>
				<listitem><para>query: 1 column</para></listitem>
				<listitem><para>order: 0 or 1 column</para></listitem>
			</itemizedlist>
			</listitem>
			<listitem><para>DB1_INSERT - performs an SQL insert
			and supports one type of column:</para>
			<itemizedlist>
				<listitem><para>query: 1 or more columns</para></listitem>
			</itemizedlist>
			</listitem>
			<listitem><para>DB1_DELETE - performs an SQL delete
			and supports one type of column:</para>
			<itemizedlist>
				<listitem><para>clause: 1 or more columns</para></listitem>
			</itemizedlist>
			</listitem>
			<listitem><para>DB1_UPDATE - performs an SQL update
			and supports two type of columns:</para>
			<itemizedlist>
				<listitem><para>clause: 0 or more columns</para></listitem>
				<listitem><para>query: 1 or more columns</para></listitem>
			</itemizedlist>
			</listitem>
			<listitem><para>DB1_REPLACE - performs an SQL replace
			and supports one type of column:</para>
			<itemizedlist>
				<listitem><para>query: 1 or more columns</para></listitem>
			</itemizedlist>
			</listitem>
		</itemizedlist>
		Please note that some databases have a restricted
		set of database command types.
	</para>
	</section>
	</section>

	<section>
	<title>To-do</title>
		<para>
		Features to be added in the future:
		</para>
		<itemizedlist>
			<listitem><para>
			full subscriber provisionning with automatic ha1/ha1b fields.
			</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>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>libxml2</emphasis>
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	<section>
	<title>Parameters</title>
	<section>
		<title><varname>xhttp_pi_root</varname> (str)</title>
		<para>
			It specifies the root path for provisionning http requests.
			The link to the provisioning web interface must be constructed
			using the following patern:
			http://[server_IP]:[tcp_port]/[xhttp_pi_root] 
		</para>
		<para>
		<emphasis>
			Default value is "pi".
		</emphasis>
		</para>
		<example>
		<title>Set <varname>xhttp_pi_root</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("xhttp_pi", "xhttp_pi_root", "pi")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>xhttp_pi_buf_size</varname> (int)</title>
		<para>
			It specifies the maximum length of the buffer (in bytes) used
			to write in the HTML 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_pi_buf_size</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("xhttp", "xhttp_pi_buf_size", 1024)
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>framework</varname> (string)</title>
		<para>
			It specifies the full path for xml framework descriptor.
		</para>
		<para>
		<emphasis>
			There's no default value. This parameter is mandatory.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>framework</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("xhttp", "framework", "/usr/local/etc/kamailio/pi_framework.xml")
...
</programlisting>
		</example>
	</section>
	</section>

	<section>
	<title>Functions</title>
 	<section>
		<title>
		<function moreinfo="none">dispatch_xhttp_pi()</function>
		</title>
		<para>
		Handle the HTTP request and generate a response.
		</para>
		<example>
		<title><function>dispatch_xhttp_pi</function> usage</title>
		<programlisting format="linespecific">
...
tcp_accept_no_cl=yes
...
loadmodule "sl.so"
loadmodule "xhttp.so"
loadmodule "xhttp_pi.so"
...
modparam("xhttp", "framework", "/usr/local/etc/kamailio/pi_framework.xml")
...
event_route[xhttp:request] {
	$var(xhttp_root) = $(hu{s.substr,0,3});
	if ($var(xhttp_root) == "/pi")
		dispatch_xhttp_pi();
	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>

	<section>
	<title>Exported RPC Functions</title>
	<section>
		<title>
		<function moreinfo="none">xhttp_pi.reload</function>
		</title>
		<para>Reloads the xml framework.</para>
		<para>Name: <emphasis>xhttp_pi.reload</emphasis></para>
		<para>Parameters: <emphasis>none</emphasis></para>
		<para>RPC Command Format:</para>
		<programlisting  format="linespecific">
		kamctl xhttp_pi.reload
		</programlisting>
	</section>
	</section>

</chapter>

