Skip to content

Commit

Permalink
dlgs: docs for params, functions and rpc commands
Browse files Browse the repository at this point in the history
  • Loading branch information
@miconda
miconda committed Jul 9, 2020
1 parent aebae41 commit cec3e86
Showing 1 changed file with 234 additions and 11 deletions.
245 changes: 234 additions & 11 deletions src/modules/dlgs/doc/dlgs_admin.xml
View file
Expand Up @@ -67,7 +67,8 @@
<section id="dlgs.p.active_lifetime">
<title><varname>active_lifetime</varname> (int)</title>
<para>
The lifetime in seconds of a dialog in memory.
The lifetime in seconds of an active dialog in memory. A dialog is
considered active after the ACK of 200OK for INVITE.
</para>
<para>
<emphasis>
Expand All @@ -80,6 +81,50 @@
...
modparam("dlgs", "active_lifetime", 3600)
...
</programlisting>
</example>
</section>
<section id="dlgs.p.init_lifetime">
<title><varname>init_lifetime</varname> (int)</title>
<para>
The lifetime in seconds of an initial dialog in memory. A dialog is
in initial state from the moment of creation until it gets to active
state. If the dialog stays longer in the initial state, then it is
destroyed by the next timer cleanup.
</para>
<para>
<emphasis>
Default value is 180 (3 minutes).
</emphasis>
</para>
<example>
<title>Set <varname>init_lifetime</varname> parameter</title>
<programlisting format="linespecific">
...
modparam("dlgs", "init_lifetime", 240)
...
</programlisting>
</example>
</section>
<section id="dlgs.p.finish_lifetime">
<title><varname>finish_lifetime</varname> (int)</title>
<para>
The lifetime in seconds of a finished dialog in memory. A dialog is
finished if the initial INVITE was not answered or the BYE was
received. Once this lifetime passes, the dialog record is removed
from memory by the next timer cleanup.
</para>
<para>
<emphasis>
Default value is 10 (seconds).
</emphasis>
</para>
<example>
<title>Set <varname>finish_lifetime</varname> parameter</title>
<programlisting format="linespecific">
...
modparam("dlgs", "finish_lifetime", 20)
...
</programlisting>
</example>
</section>
Expand Down Expand Up @@ -116,13 +161,14 @@ modparam("dlgs", "timer_interval", 60)
It has to be used for INVITE messages.
</para>
<para>
This function can be used from ANY_ROUTE.
This function can be used from REQUEST_ROUTE, BRANCH_ROUTE,
ONREPLY_ROUTE, ONSEND_ROUTE.
</para>
<example>
<title><function>dlgs_init</function> usage</title>
<programlisting format="linespecific">
...
request_route {
onsend_route {
...
if(is_method("INVITE")) {
dlgs_init("$fu", "$tu", "my data");
Expand All @@ -135,35 +181,156 @@ request_route {
</section>
<section id="dlgs.f.dlgs_update">
<title>
<function moreinfo="none">dlgs_update(src)</function>
<function moreinfo="none">dlgs_update()</function>
</title>
<para>
Update dialog state.
Update dialog state. It has to be used for SIP requests only, the
SIP responses are handled automatically.
</para>
<para>
This function can be used from ONSEND_ROUTE.
This function can be used from REQUEST_ROUTE, BRANCH_ROUTE, ONSEND_ROUTE.
</para>
<example>
<title><function>dlgs_update</function> usage</title>
<programlisting format="linespecific">
...
onsend_route {
request_route {
...
if(is_method("INVITE|ACK|BYE")) {
dlgs_init("$fu", "$tu", "my data");
if(is_method("ACK|BYE|CANCEL")) {
dlgs_update();
}
...
}
...
</programlisting>
</example>
</section>
<section id="dlgs.f.dlgs_count">
<title>
<function moreinfo="none">dlgs_count(field, op, data)</function>
</title>
<para>
Return the number of dialogs matching the filter specified by the
parameters. It does not count the dialogs that are finished (not
answered or terminated with BYE).
</para>
<para>
The field parameter can be: 'src', 'dst', 'data' to specify what
dialog attribute has to be used for matching. It can be also 'any'
to get the count of all ongoing dialogs.
</para>
<para>
The op parameter can be: 'eq' - equal; 'ne' - not equal; 're' - regex;
'sw' - start with; 'fm' - fnmatch.
</para>
<para>
In case of error or no dialog matched, it returns -1 or other negative
(false) value.
</para>
<para>
This function can be used from ANY_ROUTE.
</para>
<example>
<title><function>dlgs_count</function> usage</title>
<programlisting format="linespecific">
...
request_route {
...
$var(count) = dlgs_count("src", "eq", "$fu");
if($var(count) > 0) {
# caller has ongoing dialogs
}
...
$var(allcalls) = dlgs_count("any", "eq", "*");
if($var(allcalls) > 0) {
# there are ongoing dialogs
}
...
}
...
</programlisting>
</example>
</section>
<section id="dlgs.f.dlgs_tags_add">
<title>
<function moreinfo="none">dlgs_tags_add(vtag)</function>
</title>
<para>
Add a tag to current dialog.
</para>
<para>
This function can be used from ANY_ROUTE.
</para>
<example>
<title><function>dlgs_tags_add</function> usage</title>
<programlisting format="linespecific">
...
request_route {
...
dlgs_tags_add("$si");
...
}
...
</programlisting>
</example>
</section>
<section id="dlgs.f.dlgs_tags_rm">
<title>
<function moreinfo="none">dlgs_tags_rm(vtag)</function>
</title>
<para>
Remove a tag from current dialog.
</para>
<para>
This function can be used from ANY_ROUTE.
</para>
<example>
<title><function>dlgs_tags_rm</function> usage</title>
<programlisting format="linespecific">
...
request_route {
...
dlgs_tags_rm("$si");
...
}
...
</programlisting>
</example>
</section>
<section id="dlgs.f.dlgs_tags_count">
<title>
<function moreinfo="none">dlgs_tags_count(vtag)</function>
</title>
<para>
Count all tags for ongoing dialogs matching the parameter.
</para>
<para>
It returns -1 if no tag for ongoing dialogs is matched or there
was an error.
</para>
<para>
This function can be used from ANY_ROUTE.
</para>
<example>
<title><function>dlgs_tags_count</function> usage</title>
<programlisting format="linespecific">
...
request_route {
...
$var(tcount) = dlgs_tags_count("$si");
...
}
...
</programlisting>
</example>
</section>
</section>

<section>
<title>RPC Commands</title>
<section id="dlgs.rpc.list">
<title>
<function moreinfo="none">rpc.list</function>
<function moreinfo="none">dlgs.list</function>
</title>
<para>
List dialog records.
Expand All @@ -174,12 +341,68 @@ onsend_route {
...
&kamctl; rpc dlgs.list
...
</programlisting>
</example>
</section>
<section id="dlgs.rpc.briefing">
<title>
<function moreinfo="none">dlgs.briefing</function>
</title>
<para>
List dialog records with fewer attributes per record.
</para>
<example>
<title><function>dlgs.briefing</function> usage</title>
<programlisting format="linespecific">
...
&kamctl; rpc dlgs.briefing
...
</programlisting>
</example>
</section>
<section id="dlgs.rpc.get">
<title>
<function moreinfo="none">dlgs.get</function>
</title>
<para>
Prototype: dlgs.get field op data
</para>
<para>
List first dialog record matching the filter. The parameters have
the same meaning like those for dlgs_count(...).
</para>
<example>
<title><function>dlgs.get</function> usage</title>
<programlisting format="linespecific">
...
&kamctl; rpc dlgs.get src eq sip:alice@sipserver.com
...
</programlisting>
</example>
</section>
<section id="dlgs.rpc.getall">
<title>
<function moreinfo="none">dlgs.getall</function>
</title>
<para>
Prototype: dlgs.getall field op data
</para>
<para>
List all dialog records matching the filter. The parameters have
the same meaning like those for dlgs_count(...).
</para>
<example>
<title><function>dlgs.get</function> usage</title>
<programlisting format="linespecific">
...
&kamctl; rpc dlgs.get src eq sip:alice@sipserver.com
...
</programlisting>
</example>
</section>
<section id="dlgs.rpc.stats">
<title>
<function moreinfo="none">rpc.stats</function>
<function moreinfo="none">dlgs.stats</function>
</title>
<para>
Return dialog statistics.
Expand Down

0 comments on commit cec3e86

Please sign in to comment.