<?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 is a module which provides a UNIX/UDP SOCKET transport layer 
		implementation for the Management Interface. 
	</para>
	</section>

	<section>
	<title>DATAGRAM command syntax</title>
	<para>
		The external commands issued via DATAGRAM interface must follow the
		following syntax:
		<itemizedlist>
			<listitem><para><emphasis>
			request = first_line (argument '\n')*
			</emphasis></para></listitem>
			<listitem><para><emphasis>
			first_line = ':'command_name':''\n'
			</emphasis></para></listitem>
			<listitem><para><emphasis>
			argument = (arg_name '::' (arg_value)? ) | (arg_value)
			</emphasis></para></listitem>
			<listitem><para><emphasis>
			arg_name = not-quoted_string
			</emphasis></para></listitem>
			<listitem><para><emphasis>
			arg_value = not-quoted_string | '"' string '"'
			</emphasis></para></listitem>
			<listitem><para><emphasis>
			not-quoted_string = string - {',",\n,\r}
			</emphasis></para></listitem>
		</itemizedlist>
	</para>
	</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>none</emphasis>
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section>
	<title>Parameters</title>
	<section>
		<title><varname>socket_name</varname> (string)</title>
		<para>
		The name of a UNIX SOCKET or an IP address. 
		The UNIX datagram or UDP socket will be created using this parameter 
		in order to read the external commands.
		Both IPv4 and IPv6 are supported. 
		</para>
		<para>
		<emphasis>
			Default value is NONE.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>socket_name</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mi_datagram", "socket_name", "/tmp/kamailio.sock")
...
modparam("mi_datagram", "socket_name", "udp:192.168.2.133:8080")
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>children_count</varname> (string)</title>
		<para>
		The number of child processes to be created. Each child process
		will be a datagram server.
		</para>
		<para>
		<emphasis>
			Default value is 1.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>children_count</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mi_datagram", "children_count", 3)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>unix_socket_mode</varname> (integer)</title>
		<para>
		Permission to be used for creating the listening UNIX datagram socket. 
		Not necessary for a UDP socket.
		It follows the UNIX conventions.
		</para>
		<para>
		<emphasis>
			Default value is 0660 (rw-rw----).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>unix_socket_mode</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mi_datagram", "unix_socket_mode", 0600)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>unix_socket_group</varname> (integer)
		<varname>unix_socket_group</varname> (string)</title>
		<para>
		Group to be used for creating the listening UNIX socket.
		</para>
		<para>
		<emphasis>
			Default value is the inherited one.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>unix_socket_group</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mi_datagram", "unix_socket_group", 0)
modparam("mi_datagram", "unix_socket_group", "root")
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>unix_socket_user</varname> (integer)
		<varname>unix_socket_group</varname> (string)</title>
		<para>
		User to be used for creating the listening UNIX socket.
		</para>
		<para>
		<emphasis>
			Default value is the inherited one.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>unix_socket_user</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mi_datagram", "unix_socket_user", 0)
modparam("mi_datagram", "unix_socket_user", "root")
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>socket_timeout</varname> (integer)</title>
		<para>
		The reply will expire after trying to sent it for socket_timeout 
		miliseconds. 
		</para>
		<para>
		<emphasis>
			Default value is 2000.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>socket_timeout</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mi_datagram", "socket_timeout", 2000)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>reply_indent</varname> (string)</title>
		<para>
		Strings to be used for line indentation. As the MI data structure 
		is tree oriendeted, the depth level will printed as identation.
		</para>
		<para>
		<emphasis>
			Default value is <quote>"\t" (TAB)</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>reply_ident</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mi_datagram", "reply_ident", "    ")
...
</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 DATAGRAM format for the 
		<quote>get_statistics dialog: tm:</quote> MI commad:
		response.
		</para>
		<example>
		<title>DATAGRAM request</title>
		<programlisting format="linespecific">

:get_statistics:\n
dialog:\n
tm:\n

</programlisting>
		</example>

	</section>


</chapter>

