mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
2610 lines
70 KiB
2610 lines
70 KiB
<?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 "../../../docbook/entities.xml">
|
|
%docentities;
|
|
|
|
]>
|
|
<!-- Module User's Guide -->
|
|
|
|
<chapter>
|
|
|
|
<title>&adminguide;</title>
|
|
|
|
<section>
|
|
<title>Overview</title>
|
|
<para>
|
|
Kamailio can behave as a stateful proxy through the TM module. However,
|
|
"stateful" in this context refers to <emphasis>transaction</emphasis>
|
|
state, not dialog state. Certain applications benefit from the proxy's
|
|
awareness of "calls", not just SIP transactions.
|
|
</para>
|
|
<para>For example, a common need is to limit the number of calls that can
|
|
be made concurrently by an endpoint, account, user group, etc. In order
|
|
to count the number of calls in progress, it is necessary for the proxy
|
|
to be aware of whole dialogs, not just transactions, and to provide some
|
|
means of programmatically classifying these dialogs. This is just one
|
|
common application discussed for illustrative purposes; there are many others.
|
|
</para>
|
|
<para>
|
|
The dialog module provides dialog awareness for the &kamailio; proxy. Its
|
|
functionality is to keep track of the current dialogs, to offer information
|
|
about them (e.g. how many dialogs are active), and to manage various
|
|
characteristics of dialogs. The module exports several functions that could be
|
|
used directly from the configuration route script.
|
|
</para>
|
|
<para>
|
|
This module also provides a foundational API on which to build
|
|
more complex dialog-oriented functionality in other &kamailio; modules.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>How it works</title>
|
|
<para>
|
|
To create the dialog associated with 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 is processed.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Dialog states</title>
|
|
<para>
|
|
Dialogs have states that are shown in the RPC interface as well as stored
|
|
in the database.
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>1</emphasis> : Unconfirmed dialog</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>2</emphasis> : Early dialog (ringing)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>3</emphasis> : Confirmed dialog (waiting for ACK)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>4</emphasis> : Confirmed dialog (active call)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>5</emphasis> : Deleted dialog</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Dialog profiling</title>
|
|
<para>
|
|
Dialog profiling is a mechanism that helps in classifying, sorting and
|
|
keeping track of certain types of dialogs. The classification criteria
|
|
can be any attributes desired by the user; they can come from SIP message
|
|
attributes, other pseudo-variables, custom values, etc.
|
|
Dialogs can be dynamically added into one or more profile
|
|
tables. Logically, each profile table can have a special meaning (like
|
|
dialogs outside the domain, dialogs terminated to the PSTN, etc.).
|
|
</para>
|
|
<para>
|
|
There are two types of profiles:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>with no value</emphasis> - a dialog simply belongs
|
|
to a profile (for instance, an outbound calls profile). There is
|
|
no other additional information to describe the dialog beyond
|
|
its membership in the profile per se.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>with value</emphasis> - a dialog belongs to a profile
|
|
having a certain value (like in a caller profile, where the value
|
|
is the caller ID). The membership of the dialog in the profile is
|
|
strictly related to the value. For example, if the account ID
|
|
of the caller is stored in the pseudo-variable $var(account_id),
|
|
you can use $var(account_id) as a value/key by which to group
|
|
dialogs so that you can count the number of open dialogs for
|
|
each account, enforce concurrent call limits as necessary, etc.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
A dialog can be added to multiple profiles at the same time.
|
|
</para>
|
|
<para>
|
|
Profiles are visible (at the moment) in the request route (for initial
|
|
and sequential requests) and in the branch, failure and reply routes of
|
|
the original request.
|
|
</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>TM</emphasis> - Transaction module
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>RR</emphasis> - Record-Route module
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>PV</emphasis> - Pseudovariables module
|
|
</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>enable_stats</varname> (integer)</title>
|
|
<para>
|
|
If statistics support should be enabled or not. Via statistics
|
|
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 two.
|
|
</para>
|
|
<para>
|
|
IMPORTANT: If dialogs' information should be stored in a database,
|
|
a constant hash_size should be used, otherwise the restoring process
|
|
will not take place. If you really want to modify the hash_size, you
|
|
must delete all table's rows before restarting the server.
|
|
</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 used to store the dialog cookie.
|
|
It is used for the fast matching of sequential requests to tracked
|
|
dialogs.
|
|
</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 (this 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 that contains a custom timeout value (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), in the absence of a custom
|
|
value provided in an AVP.
|
|
</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>dlg_extra_hdrs</varname> (string)</title>
|
|
<para>
|
|
A string containing the extra headers (full format, with EOH)
|
|
to be added to requests generated locally by the module (like BYEs).
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>NULL</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>dlf_extra_hdrs</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "dlg_extra_hdrs", "Hint: credit expired\r\n")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>dlg_match_mode</varname> (integer)</title>
|
|
<para>
|
|
How the sequential requests should be matched against the known dialogs.
|
|
The modes are a combination of matching based on a cookie (DID)
|
|
stored as cookie in Record-Route header and matching based on SIP
|
|
elements (as in RFC 3261).
|
|
</para>
|
|
<para>
|
|
Note: DID-based matching does not replace callid/fromtag/totag comparison. It will speed
|
|
up dialog matching by not iterating over the whole dialog list for callid/fromtag/totag comparison, but
|
|
instead it uses a hash table to find the respective dialog and then doing only one callid/fromtag/totag
|
|
comparison. Thus, there is no security
|
|
issue when using DID based matching. Use DID_FALLBACK for maximum interoperability or use DID_ONLY to
|
|
reject buggy clients or hacking attempts. DID_NONE is only useful, when you want to hide dialog-tracking
|
|
from the users (preventing the DID Record-Route cookie).
|
|
</para>
|
|
<para>
|
|
The supported modes are:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>0 - DID_ONLY</emphasis> - the match is done
|
|
exclusively based on DID;
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>1 - DID_FALLBACK</emphasis> - the match is first
|
|
tried based on DID and if not present, it will fall back to
|
|
SIP matching;
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>2 - DID_NONE</emphasis> - the match is done
|
|
exclusively based on SIP elements; no DID information is added
|
|
in RR.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0 (DID_ONLY)</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>dlg_match_mode</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "dlg_match_mode", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>detect_spirals</varname> (integer)</title>
|
|
<para>
|
|
Whether spirals (i.e., messages routed through the proxy multiple times)
|
|
should be detected.
|
|
</para>
|
|
<para>
|
|
If set to 0, spirals will not be detected and result in the generation of a
|
|
new, possibly dangling dialog structure per occurring spiral. If set to 1,
|
|
spirals are detected and internally mapped to existing dialog structures.
|
|
</para>
|
|
<para>
|
|
Default value is 1.
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>detect_spirals</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "detect_spirals", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>db_url</varname> (string)</title>
|
|
<para>
|
|
If you want to store the information about the dialogs in a database,
|
|
a database URL must be specified.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>&defaultdb;</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>db_url</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "db_url", "&exampledb;")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>db_mode</varname> (integer)</title>
|
|
<para>
|
|
Mode of synchronisation of dialog information from memory to an
|
|
underlying database (if desired):
|
|
</para>
|
|
<para>
|
|
The supported modes are:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>0 - NO_DB</emphasis> - the memory content is not
|
|
flushed into DB;
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>1 - REALTIME</emphasis> - any dialog information
|
|
changes will be reflected into the database immediatly.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>2 - DELAYED</emphasis> - the dialog information
|
|
changes will be flushed into DB periodically, based on a
|
|
timer routine.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>3 - SHUTDOWN</emphasis> - the dialog information
|
|
will be flushed into DB only at shutdown - no runtime updates.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>db_mode</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "db_mode", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>db_update_period</varname> (integer)</title>
|
|
<para>
|
|
The interval (seconds) at which to update dialogs' information, if you chose to store the dialogs' info at a given interval.
|
|
Too short an interval will generate intensive database operations, while an excessively long one will miss dialogs with a short lifetime.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>60</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>db_update_period</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "db_update_period", 120)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>db_fetch_rows</varname> (integer)</title>
|
|
<para>
|
|
The number of the rows to be fetched at once from database when loading the dialog records at startup from the database.
|
|
This value can be used to tune the load time at startup. For 1MB of private memory (default), it should be below 400.
|
|
The database driver must support the fetch_result() capability. A value of 0 means the database fetch is not limited.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>200</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>db_fetch_rows</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "db_fetch_rows", 500)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>db_skip_load</varname> (integer)</title>
|
|
<para>
|
|
Set db_skip_load to 1, to skip the loading of dialogs from the database alltogether.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0</quote> ( not skipped ).
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>db_skip_load</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "db_skip_load", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
|
|
|
|
<section>
|
|
<title><varname>table_name</varname> (string)</title>
|
|
<para>
|
|
If you want to store the information about the dialogs in a
|
|
database a table name must be specified.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>dialog</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>table_name</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "table_name", "my_dialog")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>call_id_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store the dialogs' callid.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>callid</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>callid_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "call_id_column", "callid_c_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>from_uri_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store the caller's
|
|
sip address.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>from_uri</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>from_uri_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "from_uri_column", "from_uri_c_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>from_tag_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store the From tag from
|
|
the INVITE request.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>from_tag</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>from_tag_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "from_tag_column", "from_tag_c_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>to_uri_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store the callee's sip address.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>to_uri</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>to_uri_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "to_uri_column", "to_uri_c_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
|
|
<section>
|
|
<title><varname>to_tag_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store the To tag from
|
|
the 200 OK response to the INVITE request, if present.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>to_tag</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>to_tag_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "to_tag_column", "to_tag_c_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>from_cseq_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store the cseq from caller
|
|
side.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>caller_cseq</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>from_cseq_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "from_cseq_column", "column_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>to_cseq_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store the cseq from callee
|
|
side.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>callee_cseq</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>to_cseq_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "to_cseq_column", "column_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>from_route_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store the route records from
|
|
caller side (proxy to caller).
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>caller_route_set</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>from_route_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "from_route_column", "column_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>to_route_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store the route records from
|
|
callee side (proxy to callee).
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>callee_route_set</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>to_route_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "to_route_column", "column_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>from_contact_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store the caller's contact
|
|
uri.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>caller_contact</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>from_contact_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "from_contact_column", "column_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>to_contact_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store the callee's contact
|
|
uri.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>callee_contact</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>to_contact_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "to_contact_column", "column_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>from_sock_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store the information about
|
|
the local interface receiving the traffic from caller.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>caller_sock</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>from_sock_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "from_sock_column", "column_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>to_sock_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store information about the
|
|
local interface receiving the traffic from callee.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>callee_sock</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>to_sock_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "to_sock_column", "column_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>h_id_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store the dialogs'
|
|
hash id information.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>hash_id</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>h_id_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "h_id_column", "hash_id_c_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>h_entry_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store the dialogs' hash
|
|
entry information.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>hash_entry</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>h_entry_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "h_entry_column", "h_entry_c_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>state_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store the
|
|
dialogs' state information.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>state</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>state_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "state_column", "state_c_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>start_time_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store the
|
|
dialogs' start time information.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>start_time</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>start_time_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "start_time_column", "start_time_c_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>timeout_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store the dialogs' timeout.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>timeout</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>timeout_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "timeout_column", "timeout_c_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>sflags_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store the script flags.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>sflags</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>sflags_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "sflags_column", "s_flags")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>toroute_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store the index of the
|
|
route to be executed at timeout.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>toroute_name</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>toroute_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "toroute_column", "timeout_route")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>vars_table_name</varname> (string)</title>
|
|
<para>
|
|
If you want to store the variables for a dialog in a
|
|
database a table name must be specified.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>dialog_vars</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>vars_table_name</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "vars_table_name", "my_dialog_vars")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>vars_h_id_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store the dialogs'
|
|
hash id information (as a reference to the dialog table).
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>hash_id</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>vars_h_id_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "vars_h_id_column", "vars_h_id_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>vars_h_entry_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store the dialogs'
|
|
hash entry information (as a reference to the dialog table).
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>hash_entry</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>vars_h_entry_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "vars_h_entry_column", "vars_h_entry_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>vars_key_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store the keys of a variable.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>dialog_key</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>vars_key_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "vars_key_column", "vars_key_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>vars_value_column</varname> (string)</title>
|
|
<para>
|
|
The column name in the database to store the keys of a variable.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>dialog_value</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>vars_value_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "vars_value_column", "vars_value_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>profiles_with_value</varname> (string)</title>
|
|
<para>
|
|
List of names for profiles with values.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>empty</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>profiles_with_value</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "profiles_with_value", "caller ; my_profile")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>profiles_no_value</varname> (string)</title>
|
|
<para>
|
|
List of names for profiles without values.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>empty</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>profiles_no_value</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "profiles_no_value", "inbound ; outbound")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>bridge_controller</varname> (string)</title>
|
|
<para>
|
|
SIP address to be used in From header when initiating a call bridge.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>sip:controller@kamailio.org</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>bridge_controller</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "bridge_controller", "sip:ctd@kamailio.org")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>bridge_contact</varname> (string)</title>
|
|
<para>
|
|
SIP address to be used in Contact header when doing a call bridge.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>sip:controller@kamailio.org:5060</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>bridge_contact</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "bridge_contact", "sip:ctd@127.0.0.1:5060")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>initial_cbs_inscript</varname> (int)</title>
|
|
<para>
|
|
If the initial dialog callbacks (i.e., DLGCB_CREATED and
|
|
DLGCB_SPIRALED) should be executed in-script or post-script.
|
|
If dlg_manage() is not used, the setting of this parameter does
|
|
not matter; otherwise, initial callbacks will be executed
|
|
directly after dlg_manage() is called if this parameter is
|
|
enabled. If it is disabled, initial callback execution will be
|
|
postponed until configuration script execution completes.
|
|
</para>
|
|
<para>
|
|
The supported values are:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>0 - POST-SCRIPT</emphasis> - execute initial
|
|
callbacks after the script completes;
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>1 - IN-SCRIPT</emphasis> - execute initial
|
|
callbacks during script execution, i.e., right after
|
|
dlg_manage() is called;
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>1</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>initial_cbs_inscript</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "initial_cbs_inscript", 0)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>send_bye</varname> (int)</title>
|
|
<para>
|
|
If set to 1, BYE requests will be sent out for each dialog that
|
|
timed out. It is an alternative to $dlg_ctx(timeout_bye)=1 for
|
|
all dialogs.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>send_bye</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "send_bye", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>wait_ack</varname> (int)</title>
|
|
<para>
|
|
If set to 1, dialog will be keept a bit longer in memory
|
|
in order to absorb the ACK negative replies of initial
|
|
INVITE. If not, the dialog is destroyed when negative reply
|
|
is sent out (less internal complexity).
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>1</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>wait_ack</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "wait_ack", 0)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>ka_timer</varname> (int)</title>
|
|
<para>
|
|
Keep-alive timer step - how often to execute the callback to
|
|
send dialog keep alives (SIP OPTIONS requests within dialog).
|
|
The value represents the number of seconds.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0</quote> (no keep alive).
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>ka_timer</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "ka_timer", 10)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>ka_interval</varname> (int)</title>
|
|
<para>
|
|
The interval between keep alives within dialog (SIP OPTIONS
|
|
requests), sent to caller or callee. The keep alive request
|
|
will be sent by the first callback fired by KA timer after
|
|
the ka_interval elapsed from dialog setup or previous keep-alive.
|
|
The value represents the number of seconds.
|
|
</para>
|
|
<para>
|
|
If the requests times out (generating a 408) or if the
|
|
UA responds with 481 the lifetime is set to 10 seconds.
|
|
When lifetime expires the dialog will be terminated.
|
|
Any other response (including error responses) will
|
|
reset the timers.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0</quote> (no keep alive). The lowest
|
|
settable interval is 30 seconds.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>ka_interval</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "ka_interval", 300)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>timeout_noreset</varname> (int)</title>
|
|
<para>
|
|
If set to 1, the dialog timeout won't be reset each
|
|
time a sequential request is processed.
|
|
It is an alternative to dlg_set_property("timeout-noreset") for all dialogs.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>timeout_noreset</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "timeout_noreset", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="dialog.p.timer_procs">
|
|
<title><varname>timer_procs</varname> (int)</title>
|
|
<para>
|
|
If set to 1, the dialog will run own timer process to execute
|
|
dialog timeout tasks.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0</quote> (use core time process).
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>timer_procs</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "timer_procs", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="dialog.p.track_cseq_updates">
|
|
<title><varname>track_cseq_updates</varname> (int)</title>
|
|
<para>
|
|
Enable the callbacks for tracking if CSeq number needs to
|
|
be updated. It is the case when the INVITE has to be
|
|
authenticated to downstream provider using uac_auth() from
|
|
uac module.
|
|
</para>
|
|
<para>
|
|
This is done only for requests in downstream direction. The
|
|
CSeq difference is stored in $dlg_var(cseq_diff), be sure
|
|
this variable is not overwritten via config operation.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0</quote> (disabled).
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>track_cseq_updates</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "track_cseq_updates", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="dialog.p.lreq_callee_headers">
|
|
<title><varname>lreq_callee_headers</varname> (string)</title>
|
|
<para>
|
|
SIP headers to be added when sending local generated requests
|
|
(e.g., BYE) to callee. It can be useful when you use topoh module
|
|
with call-id masking (see the docs of topoh module).
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>null</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>lreq_callee_headers</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "lreq_callee_headers", "TH: dlh\r\n")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
|
|
<section>
|
|
<title>Functions</title>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">set_dlg_profile(profile,[value])</function>
|
|
</title>
|
|
<para>
|
|
Inserts the current dialog into a profile. Note that if the profile does
|
|
not support values, they will be silently discarded. Also, there is
|
|
no check for inserting the same dialog into the same profile multiple
|
|
times.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>profile</emphasis> - name of the profile to be
|
|
added to;
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>value</emphasis> (optional) - string value to
|
|
define the membership of the dialog in the profile. Note that the
|
|
profile must support values. Pseudo-variables are supported.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, BRANCH_ROUTE,
|
|
REPLY_ROUTE and FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>set_dlg_profile</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
set_dlg_profile("inbound_call");
|
|
set_dlg_profile("caller","$fu");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">unset_dlg_profile(profile,[value])</function>
|
|
</title>
|
|
<para>
|
|
Removes the current dialog from a profile.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>profile</emphasis> - name of the profile to be
|
|
removed from;
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>value</emphasis> (optional) - string value to
|
|
define the belonging of the dialog to the profile - note that the
|
|
profile must support values.
|
|
Pseudo-variables are supported.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from BRANCH_ROUTE,
|
|
REPLY_ROUTE and FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>unset_dlg_profile</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
unset_dlg_profile("inbound_call");
|
|
unset_dlg_profile("caller","$fu");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">is_in_profile(profile,[value])</function>
|
|
</title>
|
|
<para>
|
|
Checks if the current dialog belongs to a profile. If the profile
|
|
supports values, the check can be reinforced to take into account a
|
|
specific value, if the dialog was inserted into the profile for a
|
|
specific value. If no value is passed, only the membership of
|
|
the dialog in the profile per se is checked. Note that if the profile does
|
|
not support values, the value parameter will be silently discarded.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>profile</emphasis> - name of the profile to be
|
|
checked against;
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>value</emphasis> (optional) - string value to
|
|
further restrict the check. Pseudo-variables are supported.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, BRANCH_ROUTE,
|
|
REPLY_ROUTE and FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>is_in_profile</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if (is_in_profile("inbound_call")) {
|
|
log("this request belongs to a inbound call\n");
|
|
}
|
|
...
|
|
if (is_in_profile("caller","XX")) {
|
|
log("this request belongs to a call of user XX\n");
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">get_profile_size(profile,[value],size)</function>
|
|
</title>
|
|
<para>
|
|
Returns the number of dialogs belonging to a profile. If the profile
|
|
supports values, the check can be reinforced to take into account a
|
|
specific value, i.e. how many dialogs were inserted into the profile with
|
|
a specific value. If no value is passed, only the membersip of the
|
|
dialog in the profile per se is checked. Note that if the profile does not
|
|
support values, the value parameter will be silently discarded.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>profile</emphasis> - name of the profile to get
|
|
the size for;
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>value</emphasis> (optional) - string value to
|
|
further restrict the check. Pseudo-variables are supported;
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>size</emphasis> - an AVP or script variable to
|
|
return the profile size in.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, BRANCH_ROUTE,
|
|
REPLY_ROUTE and FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>get_profile_size</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if(get_profile_size("inbound_call","$avp(size)"))
|
|
xlog("currently there are $avp(size) inbound calls\n");
|
|
...
|
|
if(get_profile_size("caller","$fu","$avp(size)"))
|
|
xlog("currently, the user $fu has $avp(size) active outgoing calls\n");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">dlg_isflagset(flag)</function>
|
|
</title>
|
|
<para>
|
|
Check if the dialog flag is set or not.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>flag</emphasis> - index of the flag - can be
|
|
pseudo-variable.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from BRANCH_ROUTE,
|
|
REQUEST_ROUTE, ONREPLY_ROUTE and FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>dlg_isflagset</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if(dlg_isflagset("1"))
|
|
{
|
|
...
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">dlg_setflag(flag)</function>
|
|
</title>
|
|
<para>
|
|
Set the dialog flag.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>flag</emphasis> - index of the flag - can be
|
|
pseudo-variable.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from BRANCH_ROUTE,
|
|
REQUEST_ROUTE, ONREPLY_ROUTE and FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>dlg_setflag</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
dlg_setflag("1");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">dlg_resetflag(flag)</function>
|
|
</title>
|
|
<para>
|
|
Reset the dialog flag.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>flag</emphasis> - index of the flag - can be
|
|
pseudo-variable.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from BRANCH_ROUTE,
|
|
REQUEST_ROUTE, ONREPLY_ROUTE and FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>dlg_resetflag</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
redlg_setflag("1");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">dlg_bye(side)</function>
|
|
</title>
|
|
<para>
|
|
Send BYE to both parties of a dialog.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>side</emphasis> - where to send the BYE. It can be:
|
|
'caller', 'callee', or 'all' (send to both sides).
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from ANY_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>dlg_bye</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
dlg_bye("all");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">dlg_refer(side, address)</function>
|
|
</title>
|
|
<para>
|
|
Refer the 'side' to a new SIP 'address'.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>side</emphasis> - which side of the dialog to REFER. It can be:
|
|
'caller' or 'callee'.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>address</emphasis> - SIP address to refer to.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from BRANCH_ROUTE,
|
|
REQUEST_ROUTE, ONREPLY_ROUTE and FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>dlg_refer</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
dlg_refer("caller", "sip:announcement@kamailio.org");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">dlg_manage()</function>
|
|
</title>
|
|
<para>
|
|
Process current SIP request with dialog module. It is an alternative to
|
|
setting dialog flag for initial INVITE and Route-parameter-callback
|
|
execution for within-dialog requests.
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>dlg_manage</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dialog", "default_timeout", 100)
|
|
...
|
|
route {
|
|
...
|
|
if(is_method("INVITE") && !has_totag())
|
|
{
|
|
$dlg_ctx(timeout_route) = 12;
|
|
$dlg_ctx(timeout_bye) = 1;
|
|
}
|
|
dlg_manage();
|
|
...
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">dlg_bridge(from, to, op)</function>
|
|
</title>
|
|
<para>
|
|
Bridge 'from' SIP address to 'to' SIP address via outbound proxy 'op'.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>from</emphasis> - SIP address of first side to call.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>to</emphasis> - SIP address to refer <quote>from</quote> to.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>op</emphasis> - outbound proxy SIP address.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from BRANCH_ROUTE,
|
|
REQUEST_ROUTE, ONREPLY_ROUTE and FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>dlg_bridge</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
dlg_bridge("sip:user@kamailio.org", "sip:annoucement@kamailio.org",
|
|
"sip:kamailio.org:5080");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">dlg_get(callid, ftag, ttag)</function>
|
|
</title>
|
|
<para>
|
|
Search and set current dialog based on Call-ID, From-Tag and To-Tag
|
|
parameters.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>callid</emphasis> - SIP call-id.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>ftag</emphasis> - SIP From tag.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>ttag</emphasis> - SIP To tag.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from BRANCH_ROUTE,
|
|
REQUEST_ROUTE, ONREPLY_ROUTE and FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>dlg_get</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if(dlg_get("abcdef", "123", "456"))
|
|
{
|
|
dlg_bye("all");
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">is_known_dlg()</function>
|
|
</title>
|
|
<para>
|
|
This function checks if the current SIP message being processed
|
|
belongs to any transaction within an active dialog that the
|
|
dialog module is currently tracking. This is a check for
|
|
tracking of any kind, without regard to profiles.
|
|
</para>
|
|
<para>
|
|
This function has numerous potential applications, among which
|
|
is that it can be used to strengthen security for
|
|
loose-routing sequential (in-dialog) requests or responses
|
|
to them, as by providing a preventative check against
|
|
spoofing on the proxy level instead of leaving the issue
|
|
purely to the receiving UA.
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, BRANCH_ROUTE,
|
|
REPLY_ROUTE and FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>is_known_dlg()</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if(!uri == myself) {
|
|
if(is_known_dlg()) {
|
|
xlog("Request $rm from $ci is in-dialog\n");
|
|
}
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">dlg_set_timeout(timeout [, h_entry, h_id])</function>
|
|
</title>
|
|
<para>
|
|
Set the dialog timeout. Dialog timeout will be updated if it was
|
|
already set. If h_entry and h_id parameters are not provided, the
|
|
dialog will be searched based on (callid, fromtag, totag) of
|
|
currently processed SIP message.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>timeout</emphasis> - the interval in seconds after
|
|
which the dialog will time out.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>h_entry</emphasis> - h_entry value of the iternal
|
|
dialog identifier.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>h_id</emphasis> - h_id valye if the internal dialog
|
|
identifier.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from ANY_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>dlg_set_timeout</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if(dlg_set_timeout("180", "123", "456"))
|
|
{
|
|
...
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">dlg_set_timeout_by_profile(profile, [value], timeout)</function>
|
|
</title>
|
|
<para>
|
|
Like <emphasis>dlg_set_timeout()</emphasis>, but
|
|
simultaneously sets the timeout of all dialogs in
|
|
a given profile. Can be constrained by profile value.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>profile</emphasis> - The dialog profile across which to apply the timeout.
|
|
</para>
|
|
<para><emphasis>value</emphasis> (optional) - The profile value to use when applying the dialog timeout.
|
|
</para>
|
|
<para><emphasis>timeout</emphasis> - the interval in seconds after
|
|
which the dialog will time out.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from ANY_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>dlg_set_timeout_by_profile</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
# All dialogs belonging to user abc123 (tracked via set_dlg_profile())
|
|
# will be timed out in 3 seconds.
|
|
|
|
dlg_set_timeout_by_profile("users", "abc123", "3");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">dlg_set_property(attr)</function>
|
|
</title>
|
|
<para>
|
|
Set a dialog property - an attribute that enable/disable
|
|
various behaviours (e.g., sending keep alive requests).
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>attr</emphasis> - name of property. It can be:
|
|
<itemizedlist>
|
|
<listitem>
|
|
'ka-src' - send keep alive OPTION requests to caller
|
|
</listitem>
|
|
<listitem>
|
|
'ka-dst' - send keep alive OPTION requests to callee
|
|
</listitem>
|
|
<listitem>
|
|
'timeout-noreset' - don't reset timeout on in-dialog messages reception
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
If keep alive is enabled for a dialog, the module will send
|
|
SIP OPTIONS requests with CSeq lower or equal than last request
|
|
within dialog, with the scope of detecting if the destination is
|
|
still in the call. If the keep alive request results in a local
|
|
timeout or '481 Call Leg/Transaction Does Not Exist', then the
|
|
dialog is ended from the server.
|
|
</para>
|
|
<para>
|
|
If 'timeout-noreset' is set, dialog timeout won't be reset upon reception
|
|
of in-dialog messages (default behavior).
|
|
</para>
|
|
<para>
|
|
This function can be used from ANY_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>dlg_set_property</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
dlg_set_property("ka-src");
|
|
dlg_set_property("ka-dst");
|
|
dlg_set_property("timeout-noreset");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="dialog.f.dlg_remote_profile">
|
|
<title>
|
|
<function moreinfo="none">dlg_remote_profile(cmd, profile, value, uid, expires)</function>
|
|
</title>
|
|
<para>
|
|
Manage remote profile via config file. A remote profile item is considered when
|
|
the dialog is not managed by this server instance. The notification to add/remove
|
|
can be received via SIP or a RPC command, the operation can be then triggered
|
|
from configuration file. This should allow counting active dialogs in a profile
|
|
that are managed by multiple SIP server instances.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>cmd</emphasis> - the operations to do: add - add an item in
|
|
profile; rm - remove an item from profile
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>profile</emphasis> - name of profile
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>value</emphasis> - value for profile (if no value is needed
|
|
for that profile, use an empty string.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>expires</emphasis> - absolute time (unix timestamp) when this
|
|
profile item should be removed automatically (time based),
|
|
if still in the profile
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from ANY_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>dlg_remote_profile</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
$var(exp) = 3600 + $Ts;
|
|
dlg_remote_profile("add", "caller", "test", "$sruid", "$var(exp)");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
|
|
|
|
<section>
|
|
<title>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>MI Commands</title>
|
|
|
|
<section>
|
|
<title><varname>dlg_list</varname></title>
|
|
<para>
|
|
Lists the description of a dialog or of all dialogs (calls). If only
|
|
one dialogs is to be listed, the dialog identifiers are to be passed
|
|
as parameter (callid and fromtag).
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>dlg_list</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>callid</emphasis> (optional) - callid if a single
|
|
dialog to be listed.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>from_tag</emphasis> (optional, but cannot be present
|
|
without the callid parameter) - from tag (as per initial request)
|
|
of the dialog to be listed. Note that if the from_tag is not
|
|
specified, only dialogs created by a request without a from tag
|
|
are matched, which will only occur with broken clients and is
|
|
thus a very rare situation.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
MI FIFO Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
:dlg_list:_reply_fifo_file_
|
|
_empty_line_
|
|
</programlisting>
|
|
<programlisting format="linespecific">
|
|
:dlg_list:_reply_fifo_file_
|
|
abcdrssfrs122444@192.168.1.1
|
|
AAdfeEFF33
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>dlg_list_ctx</varname></title>
|
|
<para>
|
|
The same as the <quote>dlg_list</quote> but including in the dialog
|
|
description the associated context from modules sitting on top of
|
|
the dialog module.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>dlg_list_ctx</emphasis>
|
|
</para>
|
|
<para>Parameters: <emphasis>see <quote>dlg_list</quote></emphasis>
|
|
</para>
|
|
<para>
|
|
MI FIFO Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
:dlg_list_ctx:_reply_fifo_file_
|
|
_empty_line_
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>dlg_end_dlg</varname></title>
|
|
<para>
|
|
Terminates a confirmed dialog by sending BYE requests in both directions.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>dlg_end_dlg</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>h_entry</emphasis> - hash entry of the dialog in the
|
|
internal dialog table
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>h_id</emphasis> - hash id of the dialog on the hash
|
|
entry
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>extra_hdrs</emphasis> - (optional) string containg
|
|
extra headers (full format) to be added to the BYE requests.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
The values for the h_entry and h_id can be get via the dlg_list
|
|
MI command.
|
|
</para>
|
|
<para>
|
|
<emphasis>Note: Works only for confirmed dialogs.</emphasis>
|
|
</para>
|
|
<para>
|
|
MI FIFO Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
:dlg_end_dlg:_reply_fifo_file_
|
|
342
|
|
56
|
|
_empty_line_
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>dlg_terminate_dlg</varname></title>
|
|
<para>
|
|
Terminates a singe dialog, identified by a Call-ID.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>dlg_terminate_dlg</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>callid</emphasis> - callid of the dialog to be terminated.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>from_tag</emphasis> (optional, but cannot be present
|
|
without the callid parameter) - from tag (as per initial request)
|
|
of the dialog to be terminated. Note that if the from_tag is not
|
|
specified, only dialogs created by a request without a from tag
|
|
are matched, which will only occur with broken clients and is
|
|
thus a very rare situation.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
<emphasis>Note: Works only for confirmed dialogs.</emphasis>
|
|
</para>
|
|
<para>
|
|
MI FIFO Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
:dlg_terminate_dlg:_reply_fifo_file_
|
|
abcdrssfrs122444@192.168.1.1
|
|
AAdfeEFF33
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>profile_get_size</varname></title>
|
|
<para>
|
|
Returns the number of dialogs belonging to a profile. If the profile
|
|
supports values, the check can be reinforced to take into account a
|
|
specific value - how many dialogs were inserted into the profile with
|
|
a specific value. If no value is passed, only the simply belonging of
|
|
the dialog to the profile is checked. Note that if the profile does not
|
|
supports values, this will be silently discarded.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>profile_get_size</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>profile</emphasis> - name of the profile to get the
|
|
value for.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>value</emphasis> (optional)- string value to
|
|
further restrict the check;
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
MI FIFO Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
:profile_get_size:_reply_fifo_file_
|
|
inbound_calls
|
|
_empty_line_
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>profile_list_dlgs</varname></title>
|
|
<para>
|
|
Lists all the dialogs belonging to a profile. If the profile
|
|
supports values, the check can be reinforced to take into account a
|
|
specific value - list only the dialogs that were inserted into the
|
|
profile with that specific value. If no value is passed, all dialogs
|
|
belonging to the profile will be listed. Note that if the profile does
|
|
not supports values, this will be silently discarded.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>profile_list_dlgs</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>profile</emphasis> - name of the profile to list the
|
|
dialog for.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>value</emphasis> (optional)- string value to
|
|
further restrict the check;
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
MI FIFO Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
:profile_list_dlgs:_reply_fifo_file_
|
|
inbound_calls
|
|
_empty_line_
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>dlg_bridge</varname></title>
|
|
<para>
|
|
Bridge two SIP addresses in a call using INVITE(hold)-REFER-BYE
|
|
mechanism.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>dlg_bridge</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>from</emphasis> - SIP address to initiate the call
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>to</emphasis> - SIP address to refer 'from' to
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>op</emphasis> (optional) - outbound proxy SIP address
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
MI FIFO Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
:dlg_bridge:_reply_fifo_file_
|
|
from
|
|
to
|
|
op
|
|
_empty_line_
|
|
</programlisting>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
|
|
<section>
|
|
<title>Exported RPC Functions</title>
|
|
<section>
|
|
<title><varname>dlg.list</varname></title>
|
|
<para>Lists the description of all dialogs (calls). </para>
|
|
<para>Name: <emphasis>dlg.list</emphasis></para>
|
|
<para>RPC Command Format:</para>
|
|
<programlisting format="linespecific">
|
|
serctl dlg_list
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>dlg.list_ctx</varname></title>
|
|
<para>
|
|
The same as the <quote>dlg_list</quote> but including in the dialog
|
|
description the associated context from modules sitting on top of
|
|
the dialog module.
|
|
</para>
|
|
<para>Name: <emphasis>dlg.list_ctx</emphasis></para>
|
|
<para>RPC Command Format:</para>
|
|
<programlisting format="linespecific">
|
|
serctl dlg.list_ctx
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>dlg.dlg_list</varname></title>
|
|
<para>
|
|
Lists the description of one dialog. The dialog identifiers are to be passed
|
|
as parameter (callid and fromtag).
|
|
</para>
|
|
<para>Name: <emphasis>dlg.dlg_list</emphasis></para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>callid</emphasis> callid of the dialog to be listed.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>from_tag</emphasis> from tag (as per initial request)
|
|
of the dialog to be listed.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>RPC Command Format:</para>
|
|
<programlisting format="linespecific">
|
|
serctl dlg.list abcdrssfrs122444@192.168.1.1 AAdfeEFF33
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>dlg.dlg_list_ctx</varname></title>
|
|
<para>
|
|
The same as the <quote>dlg.list_ctx</quote> but including in the dialog
|
|
description the associated context from modules sitting on top of
|
|
the dialog module.
|
|
</para>
|
|
<para>Name: <emphasis>dlg.dlg_list_ctx</emphasis></para>
|
|
<para>Parameters: <emphasis>see <quote>dlg_list</quote></emphasis>
|
|
</para>
|
|
<para>RPC Command Format:</para>
|
|
<programlisting format="linespecific">
|
|
serctl dlg.list_ctx abcdrssfrs122444@192.168.1.1 AAdfeEFF33
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>dlg.end_dlg</varname></title>
|
|
<para>
|
|
Terminates an ongoing dialog by sending BYE in both directions.
|
|
</para>
|
|
<para>Name: <emphasis>dlg.end_dlg</emphasis></para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>h_entry</emphasis> - hash entry of the dialog in the
|
|
internal dialog table
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>h_id</emphasis> - hash id of the dialog on the hash
|
|
entry
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>extra_hdrs</emphasis> - (optional) string containg
|
|
extra headers (full format) to be added to the BYE requests.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
The values for the h_entry and h_id can be get via the dlg_list
|
|
RPC command.
|
|
</para>
|
|
<para>RPC Command Format:</para>
|
|
<programlisting format="linespecific">
|
|
serctl dlg.end_dlg 342 56
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>dlg.profile_get_size</varname></title>
|
|
<para>
|
|
Returns the number of dialogs belonging to a profile. If the profile
|
|
supports values, the check can be reinforced to take into account a
|
|
specific value - how many dialogs were inserted into the profile with
|
|
a specific value. If no value is passed, only the simply belonging of
|
|
the dialog to the profile is checked. Note that if the profile does not
|
|
support values, the value parameter will be silently discarded.
|
|
</para>
|
|
<para>Name: <emphasis>dlg.profile_get_size</emphasis></para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>profile</emphasis> - name of the profile to get the
|
|
value for.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>value</emphasis> (optional)- string value to
|
|
further restrict the check;
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>RPC Command Format:</para>
|
|
<programlisting format="linespecific">
|
|
serctl dlg.dlg.profile_get_size inbound_calls
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>dlg.profile_list</varname></title>
|
|
<para>
|
|
Lists all the dialogs belonging to a profile. If the profile
|
|
supports values, the check can be reinforced to take into account a
|
|
specific value, i.e. list only the dialogs that were inserted into the
|
|
profile with that specific value. If no value is passed, all dialogs
|
|
belonging to the profile will be listed. Note that if the profile does
|
|
not supports values, this will be silently discarded.
|
|
</para>
|
|
<para>Name: <emphasis>dlg.profile_list</emphasis></para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>profile</emphasis> - name of the profile to list the
|
|
dialog for.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>value</emphasis> (optional)- string value to
|
|
further restrict the check;
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>RPC Command Format:</para>
|
|
<programlisting format="linespecific">
|
|
serctl dlg.profile_list inbound_calls
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>dlg.bridge_dlg</varname></title>
|
|
<para>
|
|
Bridge two SIP addresses into a call using INVITE(hold)-REFER-BYE
|
|
mechanism.
|
|
</para>
|
|
<para>Name: <emphasis>dlg.bridge_dlg</emphasis></para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>from</emphasis> - SIP address to initiate the call
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>to</emphasis> - SIP address to refer 'from' to
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>op</emphasis> (optional) - outbound proxy SIP address
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>RPC Command Format:</para>
|
|
<programlisting format="linespecific">
|
|
serctl dlg.list from to op
|
|
</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>
|
|
<title><varname>$dlg(...)</varname></title>
|
|
<para>Access to dialog attributes.</para>
|
|
</section>
|
|
<section>
|
|
<title><varname>$dlg_ctx(...)</varname></title>
|
|
<para>Access to dialog context attributes.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>$dlg_var(key)</varname></title>
|
|
<para>
|
|
This is a read/write variable that can be used to store
|
|
custom values assigned with a dialog (e.g. the URI of a
|
|
billing-server, an assigned emergency-server).
|
|
This pseudo-variable will be available only for subsequential
|
|
requests after doing loose_route().
|
|
</para>
|
|
<para>
|
|
Note: You will receive "NULL", if there is no dialog for this
|
|
request.
|
|
</para>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Event Routes</title>
|
|
<section>
|
|
<title><varname>event_route[dialog:start]</varname></title>
|
|
<para>
|
|
Executed when 200OK for INVITE is processed.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title><varname>event_route[dialog:end]</varname></title>
|
|
<para>
|
|
Executed when BYE is processed or dialog timed out.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title><varname>event_route[dialog:failed]</varname></title>
|
|
<para>
|
|
Executed when dialog is not completed (+300 reply to INVITE).
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
</chapter>
|