$Revision: 1732 $
$Date: 2007-03-02 17:20:41 +0200 (Fri, 02 Mar 2007) $
User's Guide
Overview
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.
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.
How it works
To create the dialog associated to an initial request, the flag
dlg_flag
() must be set before
creating the corresponding transaction.
The dialog is automatically destroyed when a BYE
is
received. In case of no BYE
, the dialog lifetime is
controlled via the default timeout (see default_timeout
- ) and custom timeout (see
timeout_avp
- ). The
dialog timeout is reset each time a sequential request passes.
Dependencies
&ser; Modules
The following modules must be loaded before this module:
TM - Transaction module
RR - Record-Route module
External Libraries or Applications
The following libraries or applications must be installed before
running &ser; with this module loaded:
None.
Exported Parameters
<varname>enable_stats</varname> (integer)
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.
Default value is 1 (enabled)
.
Set <varname>enable_stats</varname> parameter
...
modparam("dialog", "enable_stats", 0)
...
<varname>hash_size</varname> (integer)
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.
Default value is 4096
.
Set <varname>hash_size</varname> parameter
...
modparam("dialog", "hash_size", 1024)
...
<varname>rr_param</varname> (string)
Name of the Record-Route parameter to be added with the dialog cookie.
It is used for fast dialog matching of the sequential requests.
Default value is did
.
Set <varname>rr_param</varname> parameter
...
modparam("dialog", "rr_param", "xyz")
...
<varname>dlg_flag</varname> (integer)
Flag to be used for marking if a dialog should be constructed for the
current request (make sense only for initial requests).
Default value is none
.
Set <varname>dlg_flag</varname> parameter
...
modparam("dialog", "dlg_flag", 4)
...
<varname>timeout_avp</varname> (string)
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
Default value is none
.
Set <varname>timeout_avp</varname> parameter
...
modparam("dialog", "timeout_avp", "$avp(i:10)")
...
<varname>default_timeout</varname> (integer)
The default dialog timeout (in seconds) if no custom one is set.
Default value is 43200 (12 hours)
.
Set <varname>default_timeout</varname> parameter
...
modparam("dialog", "default_timeout", 21600)
...
<varname>use_tight_match</varname> (integer)
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.
Default value is 0 (disabled)
.
Set <varname>use_tight_match</varname> parameter
...
modparam("dialog", "use_tight_match", 1)
...
Exported Functions
There are no exported functions that could be used in scripts.
Exported statistics
<varname>active_dialogs</varname>
Returns the number of current active dialogs (may be confirmed or
not).
<varname>early_dialogs</varname>
Returns the number of early dialogs.
<varname>processed_dialogs</varname>
Returns the total number of processed dialogs (terminated,
expired or active) from the startup.
<varname>expired_dialogs</varname>
Returns the total number of expired dialogs from the startup.
<varname>failed_dialogs</varname>
Returns the number of failed dialogs.
Exported MI Functions
<varname>dlg_list</varname>
It returns a listing of all dialogs (calls).
Name: dlg_list
Parameters: none
MI FIFO Command Format:
:dlg_list:_reply_fifo_file_
_empty_line_
Exported pseudo-variables
<varname>$DLG_count</varname>
Returns the number of current active dialogs (may be confirmed or
not).
<varname>$DLG_status</varname>
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().
Value may be:
NULL - Dialog not found.
3 - Confirmed by a final reply but
no ACK received yet.
4 - Confirmed by a final reply and
ACK received.
5 - Dialog ended.
<varname>$DLG_lifetime</varname>
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().
NULL will be returned if there is no dialog for the request.