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

<chapter id="sec-admin-guide">
	<title>&adminguide;</title>

	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
	The <emphasis>"freeswitch"</emphasis> module is a C driver for the
	FreeSWITCH Event Socket Layer interface. It can interact with one or more
	FreeSWITCH servers either by issuing commands to them, or by receiving
	events from them.
	</para>
	<para>
	This driver can be seen as a centralized FreeSWITCH ESL connection manager.
	OpenSIPS modules may use its API in order to easily establish, reference
	and reuse ESL connections.
	</para>
	<para>
	A FreeSWITCH ESL URL is of the form:
	<emphasis role='bold'>fs://[username]:password@host[:port]</emphasis>.
	The default ESL port is 8021.
	</para>
	</section>

	<section id="sec-external-dependencies">
		<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 id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>
	<section id="param_event_heartbeat_interval" xreflabel="event_heartbeat_interval">
		<title><varname>event_heartbeat_interval</varname> (integer)</title>
		<para>
		The expected interval between FreeSWITCH HEARTBEAT event arrivals.
		</para>
		<para>
		<emphasis>
			Default value is <quote>1</quote> (second).
		</emphasis>
		</para>
		<example>
		<title>Setting the <varname>event_heartbeat_interval</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("freeswitch", "event_heartbeat_interval", 20)
...
</programlisting>
		</example>
	</section>
	<section id="param_esl_connect_timeout" xreflabel="esl_connect_timeout">
		<title><varname>esl_connect_timeout</varname> (integer)</title>
		<para>
		The maximally allowed duration for the establishment of an ESL connection.
		</para>
		<para>
		<emphasis>
			Default value is <quote>5000</quote> (milliseconds).
		</emphasis>
		</para>
		<example>
		<title>Setting the <varname>esl_connect_timeout</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("freeswitch", "esl_connect_timeout", 3000)
...
</programlisting>
		</example>
	</section>
	<section id="param_esl_cmd_timeout" xreflabel="esl_cmd_timeout">
		<title><varname>esl_cmd_timeout</varname> (integer)</title>
		<para>
		The maximally allowed duration for the execution of an ESL command.
		This interval does not include the connect duration.
		</para>
		<para>
		<emphasis>
			Default value is <quote>5000</quote> (milliseconds).
		</emphasis>
		</para>
		<example>
		<title>Setting the <varname>esl_cmd_timeout</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("freeswitch", "esl_cmd_timeout", 3000)
...
</programlisting>
		</example>
	</section>
	<section id="param_esl_cmd_polling_itv" xreflabel="esl_cmd_polling_itv">
		<title><varname>esl_cmd_polling_itv</varname> (integer)</title>
		<para>
		The sleep interval used when polling for an ESL command response. Since the
		value of this parameter imposes a minimal duration for any ESL command,
		you should run OpenSIPS in debug mode in order to first determine an expected
		response time for an arbitrary ESL command, then tune this parameter accordingly.
		</para>
		<para>
		<emphasis>
			Default value is <quote>1000</quote> (microseconds).
		</emphasis>
		</para>
		<example>
		<title>Setting the <varname>esl_cmd_polling_itv</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("freeswitch", "esl_cmd_polling_itv", 3000)
...
</programlisting>
		</example>
	</section>
	</section>

	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	</section>
</chapter>
