<?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>
		This module can delegate processing of SIP requests to a group of
		workers in the configuration file by using event_route[core:pre-routing].
		The async workers have to be defined with the global parameter. The worker
		process that received the message internally does the usual execution
		of the config script, running request_route or reply_route.
	</para>
	<para>
		Note: the behaviour is different than the async module, because it does
		not create the transaction (obviously also not performing suspend).
	</para>
	<para>
		Note: it does not propagate anything set in the event_route, therefore
		any set flag, or avp, etc. are lost. The SIP message is processed by the
		delegated worker as it was fresh received from the network (including
		parsing).
	</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>None</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 id="sworker.p.xdata">
		<title>
		<function moreinfo="none">xdata (str)</function>
		</title>
		<para>
			Name of a script variable from where to take additional data to be
			passed to special worker along with the SIP message. Same variable
			will be set by the special worker, therefore it has to be a writable
			variable. Moreover, it must be a variable that can be set without
			the SIP message structure, like $var(name), otherwise it can lead to
			a crash.
		</para>
		<para>
		Default value: not set.
		</para>
		<example>
		<title><function>xdata</function> usage</title>
		<programlisting format="linespecific">
...
modparam("sworker", "xdata", "$var(xdata)")
...
</programlisting>
		</example>
	</section>
	</section>

	<section>
	<title>Functions</title>
	<section id="sworker.f.sworker_active">
		<title>
		<function moreinfo="none">sworker_active()</function>
		</title>
		<para>
		Return 1 (true) if the processing happens in an async process, or -1
		(false) if the processing is happening in a SIP receiving process.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE|CORE_REPLY_ROUTE.
		</para>
		<example>
		<title><function>sworker_active()</function> usage</title>
		<programlisting format="linespecific">
...
request_route {
    ...
    if(sworker_active()) {
    }
    ...
}
...
</programlisting>
		</example>
	</section>
	<section id="sworker.f.swork_task">
		<title>
		<function moreinfo="none">swork_task(gname)</function>
		</title>
		<para>
		Delegate the processing of SIP message to a group of async workers. The
		function is restricted to be used inside event_route[core:pre-routing].
		</para>
		<para>
		The parameter gname provides the name of the group workers, it can
		contain pseudo-variables.
		</para>
		<para>
		The function returns 1 (true) in case the task is delegated. After that,
		'drop' must be used so processing of the message does not continue to
		request_route or reply_route in the same process, it is going to be done
		by the delegated group of workers. It returns -1 (false) in case there
		was a problem delegating the processing.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE|CORE_REPLY_ROUTE.
		</para>
		<example>
		<title><function>sworker_task()</function> usage</title>
		<programlisting format="linespecific">
...
event_route[core:pre-routing] {
	if(sworker_task("default")) {
		xinfo("===== delegate processing [$Tf] [$si:$sp]\n");
		drop;
	}
	xinfo("===== processing continues [$Tf] [$si:$sp]\n");
    ...
}
...
</programlisting>
		</example>
	</section>

	</section>
</chapter>
