<?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 "../../../../doc/docbook/entities.xml">
%docentities;

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

<chapter>

	<title>&adminguide;</title>

	<section>
	<title>Overview</title>
	<para>
		The module executes event route blocks or KEMI functions on dedicated
		processes at startup, upon an RPC command or data received on a custom
		UDP socket.
	</para>
	<para>
		For startup event route, the execution can be delayed for a specified
		interval of time. The actions in the event route should be a loop or
		other tasks that run forever.
	</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>exec</varname> (str)</title>
		<para>
		The definition of an exec task. The value of the parameter must have the
		following format:
		</para>
		<itemizedlist>
		<listitem>
		<para>
		"name=_string_;wait=_number_;workers=_number_;sockaddr=_udp_socket_"
		</para>
		</listitem>
		</itemizedlist>
		<para>
			The parameter can be set multiple times to get more exec tasks in
			same configuration file.
		</para>
		<itemizedlist>
		<listitem>
		<para>
			<emphasis>name</emphasis> - name of the event route to be executed.
			When used with a KEMI embedded language, this has to be the name
			of a function from the KEMI script. The function must have a
			string parameter, which will retrieve the index of the works in
			string format.
		</para>
		</listitem>
		<listitem>
		<para>
			<emphasis>workers</emphasis> - if set to 0 or 1 the task is executed
			in a dedicated process. Any number > 1 will create more dedicated
			processes, each of them executing the startup task. For UDP data
			execution (when 'sockaddr' is set), only 1 worker process is created.
		</para>
		</listitem>
		<listitem>
		<para>
			<emphasis>wait</emphasis> - timer interval in micro-seconds to wait
			inside the dedicated process before executing the task.
		</para>
		</listitem>
		<listitem>
		<para>
			<emphasis>sockaddr</emphasis> - full UDP socket address in format
			'udp:ip:port' (example: 'udp:127.0.0.1:54321'). Received data is
			made available in the event route via $evr(data).
		</para>
		</listitem>

		</itemizedlist>
		<para>
		<emphasis>
			Default value is NULL.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>exec</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("evrexec", "exec", "name=evrexec:timer;wait=1000;workers=1;")
modparam("evrexec", "exec", "name=evrexec:udp;sockaddr=udp:127.0.0.1:4444;workers=1;")
...
event_route[evrexec:timer] {
  $var(x) = 0;
  while(1) {
    xlog("$$var(x) is $var(x)\n");
    $var(x) = $var(x) + 1;
    sleep("600");
  }
}

event_route[evrexec:udp] {
  xinfo("udp socket data: [$evr(data)] from [$evr(srcip)]\n");
}

...
</programlisting>
		</example>
	</section>
	</section>

	<section>
	<title>RPC Commands</title>
	<section id="evrexec.r.run">
		<title>evrexec.run</title>
		<para>
		Run an event_route block or a KEMI function upon an RPC command.
		</para>
		<para>
		Name: <emphasis>evroute.run</emphasis>
		</para>
		<para>Parameters:
		<itemizedlist>
			<listitem>
			<para>evname</para> - the name of the event route block or the KEMI
			function.
			</listitem>
			<listitem>
			<para>evdata</para> - (optional) - arbitrary data passed as a string,
			which is made available inside event route block as $evr(data).
			</listitem>
		</itemizedlist>
		</para>

		<para>
		RPC Command Format:
		</para>
		<programlisting  format="linespecific">
...
event_route[evrexec:test] {
   xlog("rpc command data: $evr(data)\n");
}
...
kamctl rpc evroute.run evroute:test
kamctl rpc evroute.run evroute:test mydata
...
		</programlisting>
	</section>
	</section>
</chapter>

