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

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		This module provides a simple way for capturing and handling 
		directly in the &osips; script of different events triggered through
		the &osips; Event Interface
	</para>
	<para>
		If you want to capture and handle a certian event, you need to
		define a dedicated route (<emphasis>event_route</emphasis>) into the
		&osips; script, route having as name the name/code of the
		desired event. The route is triggered (and executed) by
		the module when the corresponding event is raised by the &osips;
	</para>
	<para>
		NOTE that the triggered <emphasis>event_route</emphasis> is
		run asyncronus (and in a different process) in regards to the code or 
		process that generated the actual event.
	</para>
	<para>
		NOTE that inside the <emphasis>event_route</emphasis> you should
		NOT rely on anything more than the content provide by the event itself
		(see below variable). DO NOT assume to have access to any other
		variable or context, not even to a SIP message.
	</para>

	</section>

	<section id="event-route-parameters">
	<title>ROUTE events parameters</title>
	<para>
		<para>
		In order to retrieve the parameters of an event, the
		<emphasis>$param(name)</emphasis> variable has to be used. It's
			name can be the parameter's name, or, if an integer is specified, its
			index inside the parameter's list.
		</para>

		Example:
		<programlisting format="linespecific">
xlog("first parameters is $param(1)\n");
xlog("Pike Blocking IP is $param(ip)\n");
</programlisting>

		<emphasis>NOTE:</emphasis> An event may be triggered within a different event, leading
		to nested processing. This function will retrieve the parameters of the currently processed
		event.
	</para>
	<para>The event name can contain any non-quoted string character, but
		it is recommended to follow the syntax:
		E_<emphasis>MODULE_NAME</emphasis>_<emphasis>EXTRA_NAME</emphasis>
	</para>
	</section>

	<section>
		<title>EVENT_ROUTE usage</title>
		<para>
			In order to handle the <emphasis>E_PIKE_BLOCKED</emphasis> event,
			the following snippet can be used:

			<para>
				<example>
					<title>EVENT_ROUTE usage</title>
					<programlisting format="linespecific">
	event_route[E_PIKE_BLOCKED] {
		xlog("IP $param(ip) has been blocked\n");
	}
					</programlisting>
				</example>
			</para>
		</para>
	</section>
	
	<section>
	<title>EVENT_ROUTE socket syntax</title>
	<para>
		As the &osips; Event Interface requires, the <emphasis>event_route</emphasis>
		module uses a specific socket syntax:
		<para><emphasis>'route:' event_name</emphasis></para>
	</para>
	<para>
		Example:
		<para>
			<emphasis>route:E_PIKE_BLOCKED</emphasis>
		</para>
	</para>
	</section>

	<section id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section>
		<title>&osips; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>No dependencies on other &osips; 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 &osips; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>none</emphasis>
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>
	<para>The module does not export parameters to be used in configuration script.</para>
	</section>

	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	<para>The function does not export any function.</para>
	</section>

</chapter>

