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

<chapter>
	<chapterinfo>
	<revhistory>
		<revision>
		<revnumber>$Revision: 1827 $</revnumber>
		<date>$Date: 2007-03-12 17:22:53 +0200 (Mon, 12 Mar 2007) $</date>
		</revision>
	</revhistory>
	</chapterinfo>
	<title>User's Guide</title>
	
	<section>
	<title>Overview</title>
	<para>
	The dialog module provides dialog awareness to &ser; proxy. Its 
	functionality is to keep trace of the current dialogs, to offer information
	about them (like how many dialogs are active). The module exports no 
	functions that could be used directly from scripts.
	</para>
	<para>
	The module, via an internal API, also provide the foundation to build on 
	top of it more complex dialog-based functionalities via other &ser; 
	modules.
	</para>
	</section>

	<section>
	<title>How it works</title>
	<para>
	To create the dialog associated to an initial request, the flag 
	<quote>dlg_flag</quote> (<xref linkend="dlg-flag-id">) must be set before
	creating the corresponding transaction.
	</para>
	<para>
	The dialog is automatically destroyed when a <quote>BYE</quote> is 
	received. In case of no <quote>BYE</quote>, the dialog lifetime is 
	controlled via the default timeout (see <quote>default_timeout</quote>
	 - <xref linkend="default-timeout-id">) and custom timeout (see 
	 <quote>timeout_avp</quote> - <xref linkend="timeout-avp-id">). The 
	dialog timeout is reset each time a sequential request passes.
	</para>
	</section>


	<section>
	<title>Dependencies</title>
	<section>
		<title>&ser; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>TM</emphasis> - Transaction module
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>RR</emphasis> - Record-Route module
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>


	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before 
		running &ser; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>


	<section>
	<title>Exported Parameters</title>
	<section>
		<title><varname>enable_stats</varname> (integer)</title>
		<para>
		If the statistics support should be enabled or not. Via statistic 
		variables, the module provide information about the dialog processing.
		Set it to zero to disable or to non-zero to enable it.
		</para>
		<para>
		<emphasis>
			Default value is <quote>1 (enabled)</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>enable_stats</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialog", "enable_stats", 0)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>hash_size</varname> (integer)</title>
		<para>
		The size of the hash table internally used to keep the dialogs. A 
		larger table is much faster but consumes more memory. The hash size
		must be a power of 2 number.
		</para>
		<para>
		<emphasis>
			Default value is <quote>4096</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>hash_size</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialog", "hash_size", 1024)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>rr_param</varname> (string)</title>
		<para>
		Name of the Record-Route parameter to be added with the dialog cookie.
		It is used for fast dialog matching of the sequential requests.
		</para>
		<para>
		<emphasis>
			Default value is <quote>did</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>rr_param</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialog", "rr_param", "xyz")
...
</programlisting>
		</example>
	</section>

	<section id="dlg-flag-id">
		<title><varname>dlg_flag</varname> (integer)</title>
		<para>
		Flag to be used for marking if a dialog should be constructed for the
		current request (make sense only for initial requests).
		</para>
		<para>
		<emphasis>
			Default value is <quote>none</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>dlg_flag</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialog", "dlg_flag", 4)
...
</programlisting>
		</example>
	</section>

	<section id="timeout-avp-id">
		<title><varname>timeout_avp</varname> (string)</title>
		<para>
		The specification of an AVP to contain a custom timeout (in seconds)
		for the dialog. It may be used only in a request 
		(initial or sequential) context 
		</para>
		<para>
		<emphasis>
			Default value is <quote>none</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>timeout_avp</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialog", "timeout_avp", "$avp(i:10)")
...
</programlisting>
		</example>
	</section>

	<section id="default-timeout-id">
		<title><varname>default_timeout</varname> (integer)</title>
		<para>
		The default dialog timeout (in seconds) if no custom one is set.
		</para>
		<para>
		<emphasis>
			Default value is <quote>43200 (12 hours)</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>default_timeout</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialog", "default_timeout", 21600)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>use_tight_match</varname> (integer)</title>
		<para>
		If tight matching should be use dialog matching of sequential requests.
		By default, the matching is done only on the RR cookie; tight matching
		extra checks the callid. Set it to zero to disable or to non-zero to 
		enable it.
		</para>
		<para>
		<emphasis>
			Default value is <quote>0 (disabled)</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>use_tight_match</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialog", "use_tight_match", 1)
...
</programlisting>
		</example>
	</section>

	</section>


	<section>
	<title>Exported Functions</title>
	<para>
		There are no exported functions that could be used in scripts.
	</para>
	</section>


	<section>
	<title>Exported statistics</title>
		<section>
			<title><varname>active_dialogs</varname></title>
			<para>
			Returns the number of current active dialogs (may be confirmed or
			not).
			</para>
		</section>
		<section>
			<title><varname>early_dialogs</varname></title>
			<para>
			Returns the number of early dialogs.
			</para>
		</section>		<section>
			<title><varname>processed_dialogs</varname></title>
			<para>
			Returns the total number of processed dialogs (terminated, 
			expired or active) from the startup.
			</para>
		</section>
		<section>
			<title><varname>expired_dialogs</varname></title>
			<para>
			Returns the total number of expired dialogs from the startup.
			</para>
		</section>
		<section>
			<title><varname>failed_dialogs</varname></title>
			<para>
			Returns the number of failed dialogs.
			</para>
		</section>
	</section>


	<section>
	<title>Exported MI Functions</title>

		<section>
			<title><varname>dlg_list</varname></title>
			<para>
			It returns a listing of all dialogs (calls).
			</para>
		<para>
		Name: <emphasis>dlg_list</emphasis>
		</para>
		<para>Parameters: <emphasis>none</emphasis></para>
 		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:dlg_list:_reply_fifo_file_
		_empty_line_
		</programlisting>
		</section>
    </section>

	
	<section>
	<title>Exported pseudo-variables</title>

		<section>
			<title><varname>$DLG_count</varname></title>
			<para>
			Returns the number of current active dialogs (may be confirmed or
			not).
			</para>
		</section>

		<section>
			<title><varname>$DLG_status</varname></title>
			<para>
			Returns the status of the dialog corresponding to the processed 
			sequential request. This PV will be available only for sequential
			requests, after doing loose_route().
			</para>
			<para>
			Value may be:
			</para>
			<itemizedlist>
				<listitem><para>
					<emphasis>NULL</emphasis> - Dialog not found.
				</para></listitem>
				<listitem><para>
					<emphasis>3</emphasis> - Confirmed by a final reply but 
					no ACK received yet.
				</para></listitem>
				<listitem><para>
					<emphasis>4</emphasis> - Confirmed by a final reply and
					ACK received.
				</para></listitem>
				<listitem><para>
					<emphasis>5</emphasis> - Dialog ended.
				</para></listitem>
			</itemizedlist>
		</section>

		<section>
			<title><varname>$DLG_lifetime</varname></title>
			<para>
			Returns the duration (in seconds) of the dialog corresponding to 
			the processed sequential request. The duration is calculated from 
			the dialog confirmation and the current moment. This PV will be 
			available only for sequential requests, after doing loose_route().
			</para>
			<para>
			NULL will be returned if there is no dialog for the request.
			</para>
		</section>

	</section>



</chapter>

<!-- Keep this element at the end of the file
Local Variables:
sgml-parent-document: ("dialog.sgml" "Book" "chapter")
End:
-->
