dialog(k): A few documentation enhancements.

- Fixed some grammatical and spelling errors.
- A few stylistic modifications.
- Expanded discussion of potential use cases.

modules_k/dialog/README

@@ -16,9 +16,15 @@ Edited by
 
 Carsten Bock
 
-   Copyright © 2006 Voice Sistem SRL
+Edited by
+
+Alex Balashov
+
+   <[email protected]>
 
-   Copyright © 2011 Carsten Bock, http://www.ng-voice.com
+   Copyright © 2006 Voice Sistem SRL
+
+   Copyright © 2011 Carsten Bock, http://www.ng-voice.com
      __________________________________________________________________
 
    Table of Contents
@@ -316,48 +322,67 @@ Chapter 1. Admin Guide
 
 1. Overview
 
-   The dialog module provides dialog awareness to the Kamailio proxy. Its
+   Kamailio can behave as a stateful proxy through the TM module. However,
+   "stateful" in this context refers to transaction state, not dialog
+   state. Certain applications benefit from the proxy's awareness of
+   "calls", not just SIP transactions.
+
+   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.
+
+   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 (like how many dialogs are active) or to manage
-   them. The module exports several functions that could be used directly
-   from scripts.
+   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.
 
-   The module, via an internal API, also provide the foundation to build
-   on top of it more complex dialog-based functionalities via other
-   Kamailio modules.
+   This module also provides a foundational API on which to build more
+   complex dialog-oriented functionality in other Kamailio modules.
 
 2. How it works
 
-   To create the dialog associated to an initial request, the flag
-   "dlg_flag" (Section 5.4, "dlg_flag (integer)") must be set before
+   To create the dialog associated with an initial request, the flag
+   “dlg_flag� (Section 5.4, “dlg_flag (integer)�) 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" - Section 5.6, "default_timeout (integer)") and
-   custom timeout (see "timeout_avp" - Section 5.5, "timeout_avp
-   (string)"). The dialog timeout is reset each time a sequential request
-   passes.
+   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� - Section 5.6, “default_timeout (integer)�) and
+   custom timeout (see “timeout_avp� - Section 5.5, “timeout_avp
+   (string)�). The dialog timeout is reset each time a sequential request
+   is processed.
 
 3. Dialog profiling
 
    Dialog profiling is a mechanism that helps in classifying, sorting and
-   keeping trace of certain types of dialogs, using whatever properties of
-   the dialog (like caller, destination, type of calls, etc). Dialogs can
-   be dynamically added in different (and several) profile tables -
-   logically, each profile table can have a special meaning (like dialogs
-   outside the domain, dialogs terminated to PSTN, etc).
+   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.).
 
    There are two types of profiles:
-     * with no value - a dialog simply belongs to a profile. (like
-       outbound calls profile). There is no other additional information
-       to describe the dialog's belonging to the profile;
+     * with no value - 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.
      * with value - a dialog belongs to a profile having a certain value
-       (like in caller profile, where the value is the caller ID). The
-       belonging of the dialog to the profile is strictly related to the
-       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.
 
-   A dialog can be added to multiple profiles in the same time.
+   A dialog can be added to multiple profiles at the same time.
 
    Profiles are visible (at the moment) in the request route (for initial
    and sequential requests) and in the branch, failure and reply routes of
@@ -428,11 +453,11 @@ Chapter 1. Admin Guide
 
 5.1. enable_stats (integer)
 
-   If the statistics support should be enabled or not. Via statistic
+   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.
 
-   Default value is "1 (enabled)".
+   Default value is “1 (enabled)�.
 
    Example 1.1. Set enable_stats parameter
 ...
@@ -443,14 +468,14 @@ modparam("dialog", "enable_stats", 0)
 
    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 number.
+   must be a power of two.
 
    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
+   not take place. If you really want to modify the hash_size, you must
    delete all table's rows before restarting the server.
 
-   Default value is "4096".
+   Default value is “4096�.
 
    Example 1.2. Set hash_size parameter
 ...
@@ -459,10 +484,11 @@ modparam("dialog", "hash_size", 1024)
 
 5.3. rr_param (string)
 
-   Name of the Record-Route parameter to be added with the dialog cookie.
-   It is used for the fast dialog matching of sequential requests.
+   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.
 
-   Default value is "did".
+   Default value is “did�.
 
    Example 1.3. Set rr_param parameter
 ...
@@ -474,7 +500,7 @@ modparam("dialog", "rr_param", "xyz")
    Flag to be used for marking if a dialog should be constructed for the
    current request (this make sense only for initial requests).
 
-   Default value is "none".
+   Default value is “none�.
 
    Example 1.4. Set dlg_flag parameter
 ...
@@ -483,11 +509,11 @@ modparam("dialog", "dlg_flag", 4)
 
 5.5. timeout_avp (string)
 
-   The specification of an AVP that contain a custom timeout (in seconds)
-   for the dialog. It may be used only in a request (initial or
-   sequential) context
+   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.
 
-   Default value is "none".
+   Default value is “none�.
 
    Example 1.5. Set timeout_avp parameter
 ...
@@ -496,9 +522,10 @@ modparam("dialog", "timeout_avp", "$avp(i:10)")
 
 5.6. default_timeout (integer)
 
-   The default dialog timeout (in seconds) if no custom one is set.
+   The default dialog timeout (in seconds), in the absence of a custom
+   value provided in an AVP.
 
-   Default value is "43200 (12 hours)".
+   Default value is “43200 (12 hours)�.
 
    Example 1.6. Set default_timeout parameter
 ...
@@ -508,9 +535,9 @@ modparam("dialog", "default_timeout", 21600)
 5.7. dlg_extra_hdrs (string)
 
    A string containing the extra headers (full format, with EOH) to be
-   added in the requests generated by the module (like BYEs).
+   added to requests generated locally by the module (like BYEs).
 
-   Default value is "NULL".
+   Default value is “NULL�.
 
    Example 1.7. Set dlf_extra_hdrs parameter
 ...
@@ -520,18 +547,18 @@ modparam("dialog", "dlg_extra_hdrs", "Hint: credit expired\r\n")
 5.8. dlg_match_mode (integer)
 
    How the sequential requests should be matched against the known
-   dialogs. The modes are a combination between matching based on a cookie
-   (DID) stored as cookie in Record-Route header and the matching based on
-   SIP elements (as in RFC3261).
+   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).
 
    The supported modes are:
      * 0 - DID_ONLY - the match is done exclusively based on DID;
      * 1 - DID_FALLBACK - the match is first tried based on DID and if not
-       present, it will fallback to SIP matching;
+       present, it will fall back to SIP matching;
      * 2 - DID_NONE - the match is done exclusively based on SIP elements;
        no DID information is added in RR.
 
-   Default value is "0 (DID_ONLY)".
+   Default value is “0 (DID_ONLY)�.
 
    Example 1.8. Set dlg_match_mode parameter
 ...
@@ -541,7 +568,7 @@ modparam("dialog", "dlg_match_mode", 1)
 5.9. detect_spirals (integer)
 
    Whether spirals (i.e., messages routed through the proxy multiple
-   times) should be detected or not.
+   times) should be detected.
 
    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
@@ -557,10 +584,10 @@ modparam("dialog", "detect_spirals", 1)
 
 5.10. db_url (string)
 
-   If you want to store the information about the dialogs in a database a
-   database url must be specified.
+   If you want to store the information about the dialogs in a database, a
+   database URL must be specified.
 
-   Default value is "mysql://openser:openserrw@localhost/openser".
+   Default value is “mysql://openser:openserrw@localhost/openser�.
 
    Example 1.10. Set db_url parameter
 ...
@@ -569,7 +596,8 @@ modparam("dialog", "db_url", "dbdriver://username:password@dbhost/dbname")
 
 5.11. db_mode (integer)
 
-   Describe how to push into the DB the dialogs' information from memory.
+   Mode of synchronisation of dialog information from memory to an
+   underlying database (if desired):
 
    The supported modes are:
      * 0 - NO_DB - the memory content is not flushed into DB;
@@ -580,7 +608,7 @@ modparam("dialog", "db_url", "dbdriver://username:password@dbhost/dbname")
      * 3 - SHUTDOWN - the dialog information will be flushed into DB only
        at shutdown - no runtime updates.
 
-   Default value is "0".
+   Default value is “0�.
 
    Example 1.11. Set db_mode parameter
 ...
@@ -589,12 +617,12 @@ modparam("dialog", "db_mode", 1)
 
 5.12. db_update_period (integer)
 
-   The interval (seconds) at which to update dialogs' information if you
-   chose to store the dialogs' info at a given interval. A too short
-   interval will generate intensive database operations, a too large one
-   will not notice short dialogs.
+   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.
 
-   Default value is "60".
+   Default value is “60�.
 
    Example 1.12. Set db_update_period parameter
 ...
@@ -605,11 +633,12 @@ modparam("dialog", "db_update_period", 120)
 
    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 fetch_result()
-   capability. A value of 0 means the functionality is disabled.
+   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 functionality is
+   disabled.
 
-   Default value is "200".
+   Default value is “200�.
 
    Example 1.13. Set db_fetch_rows parameter
 ...
@@ -621,7 +650,7 @@ modparam("dialog", "db_fetch_rows", 500)
    If you want to store the information about the dialogs in a database a
    table name must be specified.
 
-   Default value is "dialog".
+   Default value is “dialog�.
 
    Example 1.14. Set table_name parameter
 ...
@@ -632,7 +661,7 @@ modparam("dialog", "table_name", "my_dialog")
 
    The column name in the database to store the dialogs' callid.
 
-   Default value is "callid".
+   Default value is “callid�.
 
    Example 1.15. Set callid_column parameter
 ...
@@ -643,7 +672,7 @@ modparam("dialog", "callid_column", "callid_c_name")
 
    The column name in the database to store the caller's sip address.
 
-   Default value is "from_uri".
+   Default value is “from_uri�.
 
    Example 1.16. Set from_uri_column parameter
 ...
@@ -655,7 +684,7 @@ modparam("dialog", "from_uri_column", "from_uri_c_name")
    The column name in the database to store the From tag from the INVITE
    request.
 
-   Default value is "from_tag".
+   Default value is “from_tag�.
 
    Example 1.17. Set from_tag_column parameter
 ...
@@ -666,7 +695,7 @@ modparam("dialog", "from_tag_column", "from_tag_c_name")
 
    The column name in the database to store the callee's sip address.
 
-   Default value is "to_uri".
+   Default value is “to_uri�.
 
    Example 1.18. Set to_uri_column parameter
 ...
@@ -678,7 +707,7 @@ modparam("dialog", "to_uri_column", "to_uri_c_name")
    The column name in the database to store the To tag from the 200 OK
    response to the INVITE request, if present.
 
-   Default value is "to_tag".
+   Default value is “to_tag�.
 
    Example 1.19. Set to_tag_column parameter
 ...
@@ -689,7 +718,7 @@ modparam("dialog", "to_tag_column", "to_tag_c_name")
 
    The column name in the database to store the cseq from caller side.
 
-   Default value is "caller_cseq".
+   Default value is “caller_cseq�.
 
    Example 1.20. Set caller_cseq_column parameter
 ...
@@ -700,7 +729,7 @@ modparam("dialog", "caller_cseq_column", "column_name")
 
    The column name in the database to store the cseq from callee side.
 
-   Default value is "callee_cseq".
+   Default value is “callee_cseq�.
 
    Example 1.21. Set callee_cseq_column parameter
 ...
@@ -712,7 +741,7 @@ modparam("dialog", "callee_cseq_column", "column_name")
    The column name in the database to store the route records from caller
    side (proxy to caller).
 
-   Default value is "caller_route_set".
+   Default value is “caller_route_set�.
 
    Example 1.22. Set caller_route_column parameter
 ...
@@ -724,7 +753,7 @@ modparam("dialog", "caller_route_column", "column_name")
    The column name in the database to store the route records from callee
    side (proxy to callee).
 
-   Default value is "callee_route_set".
+   Default value is “callee_route_set�.
 
    Example 1.23. Set to_route_column parameter
 ...
@@ -735,7 +764,7 @@ modparam("dialog", "to_route_column", "column_name")
 
    The column name in the database to store the caller's contact uri.
 
-   Default value is "from_contact".
+   Default value is “from_contact�.
 
    Example 1.24. Set caller_contact_column parameter
 ...
@@ -746,7 +775,7 @@ modparam("dialog", "caller_contact_column", "column_name")
 
    The column name in the database to store the callee's contact uri.
 
-   Default value is "callee_contact".
+   Default value is “callee_contact�.
 
    Example 1.25. Set callee_contact_column parameter
 ...
@@ -758,7 +787,7 @@ modparam("dialog", "callee_contact_column", "column_name")
    The column name in the database to store the information about the
    local interface receiving the traffic from caller.
 
-   Default value is "caller_sock".
+   Default value is “caller_sock�.
 
    Example 1.26. Set caller_sock_column parameter
 ...
@@ -770,7 +799,7 @@ modparam("dialog", "caller_sock_column", "column_name")
    The column name in the database to store information about the local
    interface receiving the traffic from callee.
 
-   Default value is "callee_contact".
+   Default value is “callee_contact�.
 
    Example 1.27. Set callee_sock_column parameter
 ...
@@ -782,7 +811,7 @@ modparam("dialog", "callee_sock_column", "column_name")
    The column name in the database to store the dialogs' hash id
    information.
 
-   Default value is "hash_id".
+   Default value is “hash_id�.
 
    Example 1.28. Set h_id_column parameter
 ...
@@ -794,7 +823,7 @@ modparam("dialog", "h_id_column", "hash_id_c_name")
    The column name in the database to store the dialogs' hash entry
    information.
 
-   Default value is "hash_entry".
+   Default value is “hash_entry�.
 
    Example 1.29. Set h_entry_column parameter
 ...
@@ -806,7 +835,7 @@ modparam("dialog", "h_entry_column", "h_entry_c_name")
    The column name in the database to store the dialogs' state
    information.
 
-   Default value is "state".
+   Default value is “state�.
 
    Example 1.30. Set state_column parameter
 ...
@@ -818,7 +847,7 @@ modparam("dialog", "state_column", "state_c_name")
    The column name in the database to store the dialogs' start time
    information.
 
-   Default value is "start_time".
+   Default value is “start_time�.
 
    Example 1.31. Set start_time_column parameter
 ...
@@ -829,7 +858,7 @@ modparam("dialog", "start_time_column", "start_time_c_name")
 
    The column name in the database to store the dialogs' timeout.
 
-   Default value is "timeout".
+   Default value is “timeout�.
 
    Example 1.32. Set timeout_column parameter
 ...
@@ -840,7 +869,7 @@ modparam("dialog", "timeout_column", "timeout_c_name")
 
    The column name in the database to store the script flags.
 
-   Default value is "sflags".
+   Default value is “sflags�.
 
    Example 1.33. Set sflags_column parameter
 ...
@@ -852,7 +881,7 @@ modparam("dialog", "sflags_column", "s_flags")
    The column name in the database to store the index of the route to be
    executed at timeout.
 
-   Default value is "toroute".
+   Default value is “toroute�.
 
    Example 1.34. Set toroute_column parameter
 ...
@@ -864,7 +893,7 @@ modparam("dialog", "toroute_column", "timeout_route")
    If you want to store the variables for a dialog in a database a table
    name must be specified.
 
-   Default value is "dialog_vars".
+   Default value is “dialog_vars�.
 
    Example 1.35. Set vars_table_name parameter
 ...
@@ -876,7 +905,7 @@ modparam("dialog", "vars_table_name", "my_dialog_vars")
    The column name in the database to store the dialogs' hash id
    information (as a reference to the dialog table).
 
-   Default value is "hash_id".
+   Default value is “hash_id�.
 
    Example 1.36. Set vars_h_id_column parameter
 ...
@@ -888,7 +917,7 @@ modparam("dialog", "vars_h_id_column", "vars_h_id_name")
    The column name in the database to store the dialogs' hash entry
    information (as a reference to the dialog table).
 
-   Default value is "hash_entry".
+   Default value is “hash_entry�.
 
    Example 1.37. Set vars_h_entry_column parameter
 ...
@@ -899,7 +928,7 @@ modparam("dialog", "vars_h_entry_column", "vars_h_entry_name")
 
    The column name in the database to store the keys of a variable.
 
-   Default value is "dialog_key".
+   Default value is “dialog_key�.
 
    Example 1.38. Set vars_key_column parameter
 ...
@@ -910,7 +939,7 @@ modparam("dialog", "vars_key_column", "vars_key_name")
 
    The column name in the database to store the keys of a variable.
 
-   Default value is "dialog_value".
+   Default value is “dialog_value�.
 
    Example 1.39. Set vars_value_column parameter
 ...
@@ -921,7 +950,7 @@ modparam("dialog", "vars_value_column", "vars_value_name")
 
    List of names for profiles with values.
 
-   Default value is "empty".
+   Default value is “empty�.
 
    Example 1.40. Set profiles_with_value parameter
 ...
@@ -932,7 +961,7 @@ modparam("dialog", "profiles_with_value", "caller ; my_profile")
 
    List of names for profiles without values.
 
-   Default value is "empty".
+   Default value is “empty�.
 
    Example 1.41. Set profiles_no_value parameter
 ...
@@ -943,7 +972,7 @@ modparam("dialog", "profiles_no_value", "inbound ; outbound")
 
    SIP address to be used in From header when initiating a call bridge.
 
-   Default value is "sip:[email protected]".
+   Default value is “sip:[email protected]â€�.
 
    Example 1.42. Set bridge_controller parameter
 ...
@@ -966,7 +995,7 @@ modparam("dialog", "bridge_controller", "sip:[email protected]")
      * 1 - IN-SCRIPT - execute initial callbacks during script execution,
        i.e., right after dlg_manage() is called;
 
-   Default value is "1".
+   Default value is “1�.
 
    Example 1.43. Set initial_cbs_inscript parameter
 ...
@@ -989,17 +1018,17 @@ modparam("dialog", "initial_cbs_inscript", "0")
    6.12. dlg_get(callid, ftag, ttag)
    6.13. is_known_dlg()
 
-6.1. set_dlg_profile(profile,[value])
+6.1.  set_dlg_profile(profile,[value])
 
    Inserts the current dialog into a profile. Note that if the profile
-   does not supports values, this will be silently discarded. Also, there
-   is no check for inserting the same dialog in the same profile for
+   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.
 
    Meaning of the parameters is as follows:
      * profile - name of the profile to be added to;
-     * value (optional) - string value to define the belonging of the
-       dialog to the profile - note that the profile must support values.
+     * value (optional) - string value to define the membership of the
+       dialog in the profile. Note that the profile must support values.
        Pseudo-variables are supported.
 
    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE, REPLY_ROUTE
@@ -1011,7 +1040,7 @@ set_dlg_profile("inbound_call");
 set_dlg_profile("caller","$fu");
 ...
 
-6.2. unset_dlg_profile(profile,[value])
+6.2.  unset_dlg_profile(profile,[value])
 
    Removes the current dialog from a profile.
 
@@ -1030,14 +1059,14 @@ unset_dlg_profile("inbound_call");
 unset_dlg_profile("caller","$fu");
 ...
 
-6.3. is_in_profile(profile,[value])
+6.3.  is_in_profile(profile,[value])
 
    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 simply belonging of the
-   dialog to the profile is checked. Note that if the profile does not
-   supports values, this will be silently discarded.
+   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.
 
    Meaning of the parameters is as follows:
      * profile - name of the profile to be checked against;
@@ -1058,14 +1087,14 @@ if (is_in_profile("caller","XX")) {
 }
 ...
 
-6.4. get_profile_size(profile,[value],size)
+6.4.  get_profile_size(profile,[value],size)
 
    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 simply belonging of the
-   dialog to the profile is checked. Note that if the profile does not
-   supports values, this will be silently discarded.
+   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.
 
    Meaning of the parameters is as follows:
      * profile - name of the profile to get the size for;
@@ -1085,7 +1114,7 @@ if(get_profile_size("caller","$fu","$avp(size)"))
     xlog("currently, the user $fu has $avp(size) active outgoing calls\n");
 ...
 
-6.5. dlg_isflagset(flag)
+6.5.  dlg_isflagset(flag)
 
    Check if the dialog flag is set or not.
 
@@ -1103,7 +1132,7 @@ if(dlg_isflagset("1"))
 }
 ...
 
-6.6. dlg_setflag(flag)
+6.6.  dlg_setflag(flag)
 
    Set the dialog flag.
 
@@ -1118,7 +1147,7 @@ if(dlg_isflagset("1"))
 dlg_setflag("1");
 ...
 
-6.7. dlg_resetflag(flag)
+6.7.  dlg_resetflag(flag)
 
    Reset the dialog flag.
 
@@ -1133,13 +1162,13 @@ dlg_setflag("1");
 redlg_setflag("1");
 ...
 
-6.8. dlg_bye(side)
+6.8.  dlg_bye(side)
 
-   Send BYE to parties in dialog.
+   Send BYE to both parties of a dialog.
 
    Meaning of the parameters is as follows:
-     * side - where to send the BYE. It can be: caller, callee or both of
-       them.
+     * side - where to send the BYE. It can be: 'caller', 'callee', or
+       both.
 
    This function can be used from BRANCH_ROUTE, REQUEST_ROUTE,
    ONREPLY_ROUTE and FAILURE_ROUTE.
@@ -1149,12 +1178,13 @@ redlg_setflag("1");
 dlg_bye("all");
 ...
 
-6.9. dlg_refer(side, address)
+6.9.  dlg_refer(side, address)
 
    Refer the 'side' to a new SIP 'address'.
 
    Meaning of the parameters is as follows:
-     * side - which part to REFER. It can be: caller or callee.
+     * side - which side of the dialog to REFER. It can be: 'caller' or
+       'callee'.
      * address - SIP address to refer to.
 
    This function can be used from BRANCH_ROUTE, REQUEST_ROUTE,
@@ -1162,12 +1192,12 @@ dlg_bye("all");
 
    Example 1.52. dlg_refer usage
 ...
-dlg_refer("caller", "sip:[email protected]");
+dlg_refer("caller", "sip:announ[email protected]");
 ...
 
-6.10. dlg_manage()
+6.10.  dlg_manage()
 
-   Process current SIP request with dialog module. It is alternative to
+   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.
 
@@ -1189,13 +1219,13 @@ route {
 }
 ...
 
-6.11. dlg_bridge(from, to, op)
+6.11.  dlg_bridge(from, to, op)
 
    Bridge 'from' SIP address to 'to' SIP address via outbound proxy 'op'.
 
    Meaning of the parameters is as follows:
      * from - SIP address of first side to call.
-     * to - SIP address to refer "from" to.
+     * to - SIP address to refer “from� to.
      * op - outbound proxy SIP address.
 
    This function can be used from BRANCH_ROUTE, REQUEST_ROUTE,
@@ -1207,7 +1237,7 @@ dlg_bridge("sip:[email protected]", "sip:[email protected]",
    "sip:kamailio.org:5080");
 ...
 
-6.12. dlg_get(callid, ftag, ttag)
+6.12.  dlg_get(callid, ftag, ttag)
 
    Search and set current dialog based on Call-ID, From-Tag and To-Tag
    parameters.
@@ -1228,7 +1258,7 @@ if(dlg_get("abcdef", "123", "456"))
 }
 ...
 
-6.13. is_known_dlg()
+6.13.  is_known_dlg()
 
    This function checks if the current SIP message being processed belongs
    to any transaction within an active dialog that the dialog module is
@@ -1317,12 +1347,12 @@ if(!uri == myself) {
 
 8.2. dlg_list_ctx
 
-   The same as the "dlg_list" but including in the dialog description the
+   The same as the “dlg_list� but including in the dialog description the
    associated context from modules sitting on top of the dialog module.
 
    Name: dlg_list_ctx
 
-   Parameters: see "dlg_list"
+   Parameters: see “dlg_list�
 
    MI FIFO Command Format:
                 :dlg_list_ctx:_reply_fifo_file_
@@ -1455,7 +1485,7 @@ if(!uri == myself) {
 
 9.2. dlg.list_ctx
 
-   The same as the "dlg_list" but including in the dialog description the
+   The same as the “dlg_list� but including in the dialog description the
    associated context from modules sitting on top of the dialog module.
 
    Name: dlg.list_ctx
@@ -1480,13 +1510,13 @@ if(!uri == myself) {
 
 9.4. dlg.dlg_list_ctx
 
-   The same as the "dlg.list_ctx" but including in the dialog description
+   The same as the “dlg.list_ctx� but including in the dialog description
    the associated context from modules sitting on top of the dialog
    module.
 
    Name: dlg.dlg_list_ctx
 
-   Parameters: see "dlg_list"
+   Parameters: see “dlg_list�
 
    RPC Command Format:
                 serctl dlg.list_ctx [email protected] AAdfeEFF33
@@ -1516,7 +1546,7 @@ if(!uri == myself) {
    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.
+   support values, the value parameter will be silently discarded.
 
    Name: dlg.profile_get_size
 
@@ -1531,10 +1561,10 @@ if(!uri == myself) {
 
    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.
+   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.
 
    Name: dlg.profile_list
 
@@ -1547,7 +1577,7 @@ if(!uri == myself) {
 
 9.8. dlg.bridge_dlg
 
-   Bridge two SIP addresses in a call using INVITE(hold)-REFER-BYE
+   Bridge two SIP addresses into a call using INVITE(hold)-REFER-BYE
    mechanism.
 
    Name: dlg.bridge_dlg
@@ -1625,7 +1655,7 @@ Chapter 2. Developer Guide
    1.1. register_dlgcb (dialog, type, cb, param, free_param_cb)
    1.2. terminate_dlg (dlg, hdrs)
 
-1.1. register_dlgcb (dialog, type, cb, param, free_param_cb)
+1.1.  register_dlgcb (dialog, type, cb, param, free_param_cb)
 
    Register a new callback to the dialog.
 
@@ -1667,14 +1697,14 @@ Chapter 2. Developer Guide
           + DLGCB_SPIRALED - called when the dialog matches a spiraling
             request - it's a per dialog type.
           + DLGCB_DESTROY
-     * dialog_cb cb - callback function to be called. Prototype is: "void
+     * dialog_cb cb - callback function to be called. Prototype is: “void
        (dialog_cb) (struct dlg_cell* dlg, int type, struct dlg_cb_params *
-       params); "
+       params); �
      * void *param - parameter to be passed to the callback function.
      * param_free callback_param_free - callback function to be called to
-       free the param. Prototype is: "void (param_free_cb) (void *param);"
+       free the param. Prototype is: “void (param_free_cb) (void *param);�
 
-1.2. terminate_dlg (dlg, hdrs)
+1.2.  terminate_dlg (dlg, hdrs)
 
    Terminate a Dialog
 
@@ -1685,46 +1715,46 @@ Chapter 2. Developer Guide
 
 Chapter 3. Frequently Asked Questions
 
-   3.1. What happend with "use_tight_match" parameter?
+   3.1. What happend with “use_tight_match� parameter?
    3.2. Where can I find more about Kamailio?
    3.3. Where can I post a question about this module?
    3.4. How can I report a bug?
 
    3.1.
 
-   What happend with "use_tight_match" parameter?
+       What happend with “use_tight_match� parameter?
 
-   The parameter was removed with version 1.3 as the option of tight
-   matching became mandatory and not configurable. Now, the tight matching
-   is done all the time (when using DID matching).
+       The parameter was removed with version 1.3 as the option of tight
+       matching became mandatory and not configurable. Now, the tight matching
+       is done all the time (when using DID matching).
 
    3.2.
 
-   Where can I find more about Kamailio?
+       Where can I find more about Kamailio?
 
-   Take a look at http://www.kamailio.org/.
+       Take a look at http://www.kamailio.org/.
 
    3.3.
 
-   Where can I post a question about this module?
+       Where can I post a question about this module?
 
-   First at all check if your question was already answered on one of our
-   mailing lists:
-     * User Mailing List -
-       http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-users
-     * Developer Mailing List -
-       http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev
+       First at all check if your question was already answered on one of our
+       mailing lists:
+         * User Mailing List -
+           http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-users
+         * Developer Mailing List -
+           http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev
 
-   E-mails regarding any stable Kamailio release should be sent to
-   <[email protected]> and e-mails regarding development
-   versions should be sent to <[email protected]>.
+       E-mails regarding any stable Kamailio release should be sent to
+       <[email protected]> and e-mails regarding development
+       versions should be sent to <[email protected]>.
 
-   If you want to keep the mail private, send it to
-   <[email protected]>.
+       If you want to keep the mail private, send it to
+       <[email protected]>.
 
    3.4.
 
-   How can I report a bug?
+       How can I report a bug?
 
-   Please follow the guidelines provided at:
-   http://sip-router.org/tracker.
+       Please follow the guidelines provided at:
+       http://sip-router.org/tracker.

modules_k/dialog/doc/dialog.xml

@@ -43,6 +43,11 @@
 			<email>[email protected]</email>
 		</address>
 		</editor>
+		<editor>
+			<firstname>Alex</firstname>
+			<surname>Balashov</surname>
+			<email>[email protected]</email>
+		</editor>
 	</authorgroup>
 	<copyright>
 		<year>2006</year>

modules_k/dialog/doc/dialog_admin.xml

@@ -16,22 +16,35 @@
 	<section>
 	<title>Overview</title>
 	<para>
-	The dialog module provides dialog awareness to the &kamailio; proxy. Its
+	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 (like how many dialogs are active) or to manage them. The module
-	exports several functions that could be used directly from scripts.
+	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>
-	The module, via an internal API, also provide the foundation to build on
-	top of it more complex dialog-based functionalities via other &kamailio;
-	modules.
+	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 to an initial request, the flag
+	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>
@@ -41,7 +54,7 @@
 	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.
+	dialog timeout is reset each time a sequential request is processed.
 	</para>
 	</section>
 
@@ -49,11 +62,12 @@
 	<title>Dialog profiling</title>
 	<para>
 	Dialog profiling is a mechanism that helps in classifying, sorting and
-	keeping trace of certain types of dialogs, using whatever properties of
-	the dialog (like caller, destination, type of calls, etc).
-	Dialogs can be dynamically added in different (and several) profile
-	tables - logically, each profile table can have a special meaning (like
-	dialogs outside the domain, dialogs terminated to PSTN, etc).
+	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:
@@ -61,23 +75,27 @@
 		<listitem>
 		<para>
 			<emphasis>with no value</emphasis> - a dialog simply belongs
-			to a profile. (like outbound calls profile). There is no other
-			additional information to describe the dialog's belonging to the
-			profile;
+			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 caller profile, where the value
-			is the caller ID). The belonging of the dialog to the profile is
-			strictly related to the value.
+			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 in the same time.
+	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
@@ -130,7 +148,7 @@
 	<section>
 		<title><varname>enable_stats</varname> (integer)</title>
 		<para>
-		If the statistics support should be enabled or not. Via statistic
+		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>
@@ -154,12 +172,12 @@ modparam("dialog", "enable_stats", 0)
 		<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 number.
+		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
+		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>
@@ -180,8 +198,9 @@ modparam("dialog", "hash_size", 1024)
 	<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 the fast dialog matching of sequential requests.
+		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>
@@ -222,9 +241,9 @@ modparam("dialog", "dlg_flag", 4)
 	<section id="timeout-avp-id">
 		<title><varname>timeout_avp</varname> (string)</title>
 		<para>
-		The specification of an AVP that contain a custom timeout (in seconds)
+		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
+		context.
 		</para>
 		<para>
 		<emphasis>
@@ -244,7 +263,8 @@ modparam("dialog", "timeout_avp", "$avp(i:10)")
 	<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.
+		The default dialog timeout (in seconds), in the absence of a custom
+		value provided in an AVP.
 		</para>
 		<para>
 		<emphasis>
@@ -265,7 +285,7 @@ modparam("dialog", "default_timeout", 21600)
 		<title><varname>dlg_extra_hdrs</varname> (string)</title>
 		<para>
 		A string containing the extra headers (full format, with EOH)
-		to be added in the requests generated by the module (like BYEs).
+		to be added to requests generated locally by the module (like BYEs).
 		</para>
 		<para>
 		<emphasis>
@@ -286,9 +306,9 @@ modparam("dialog", "dlg_extra_hdrs", "Hint: credit expired\r\n")
 		<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 between matching based on a cookie (DID)
-		stored as cookie in Record-Route header and the matching based on SIP
-		elements (as in RFC3261).
+		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>
 		The supported modes are:
@@ -300,7 +320,7 @@ modparam("dialog", "dlg_extra_hdrs", "Hint: credit expired\r\n")
 			</para></listitem>
 			<listitem><para>
 				<emphasis>1 - DID_FALLBACK</emphasis> - the match is first
-				tried based on DID and if not present, it will fallback to
+				tried based on DID and if not present, it will fall back to
 				SIP matching;
 			</para></listitem>
 			<listitem><para>
@@ -328,7 +348,7 @@ modparam("dialog", "dlg_match_mode", 1)
 		<title><varname>detect_spirals</varname> (integer)</title>
 		<para>
 			Whether spirals (i.e., messages routed through the proxy multiple times)
-			should be detected or not.
+			should be detected.
 		</para>
 		<para>
 			If set to 0, spirals will not be detected and result in the generation of a
@@ -351,8 +371,8 @@ modparam("dialog", "detect_spirals", 1)
 	<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.
+		If you want to store the information about the dialogs in a database,
+		a database URL must be specified.
 		</para>
 		<para>
 		<emphasis>
@@ -372,7 +392,8 @@ modparam("dialog", "db_url", "&exampledb;")
 <section>
 		<title><varname>db_mode</varname> (integer)</title>
 		<para>
-		Describe how to push into the DB the dialogs' information from memory.
+		Mode of synchronisation of dialog information from memory to an
+		underlying database (if desired):
 		</para>
 		<para>
 		The supported modes are:
@@ -414,8 +435,8 @@ modparam("dialog", "db_mode", 1)
 <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.
-			A too short interval will generate intensive database operations, a too large one will not notice short dialogs.
+			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>
@@ -436,8 +457,8 @@ modparam("dialog", "db_update_period", 120)
 		<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 fetch_result() capability. A value of 0 means the functionality is disabled.
+			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 functionality is disabled.
 		</para>
 		<para>
 		<emphasis>
@@ -1105,8 +1126,8 @@ modparam("dialog", "initial_cbs_inscript", "0")
 		</title>
 		<para>
 		Inserts the current dialog into a profile. Note that if the profile does
-		not supports values, this will be silently discarded. Also, there is
-		no check for inserting the same dialog in the same profile for multiple
+		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>
@@ -1118,9 +1139,8 @@ modparam("dialog", "initial_cbs_inscript", "0")
 		</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.
+			define the membership of the dialog in the profile.  Note that the
+			profile must support values.  Pseudo-variables are supported.
 			</para>
 		</listitem>
 		</itemizedlist>
@@ -1184,10 +1204,10 @@ unset_dlg_profile("caller","$fu");
 		<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 simply belonging of
-		the  dialog to the profile is checked. Note that if the profile does
-		not supports values, this will be silently discarded.
+		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>
@@ -1229,10 +1249,10 @@ if (is_in_profile("caller","XX")) {
 		<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 simply belonging of the
-		dialog to the profile is checked. Note that if the profile does not
-		supports values, this will be silently discarded.
+		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>
@@ -1365,13 +1385,13 @@ redlg_setflag("1");
 		<function moreinfo="none">dlg_bye(side)</function>
 		</title>
 		<para>
-		Send BYE to parties in dialog.
+		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 both of them.
+				'caller', 'callee', or both.
 			</para>
 		</listitem>
 		</itemizedlist>
@@ -1399,8 +1419,8 @@ dlg_bye("all");
 		<para>Meaning of the parameters is as follows:</para>
 		<itemizedlist>
 		<listitem>
-			<para><emphasis>side</emphasis> - which part to REFER. It can be:
-				caller or callee.
+			<para><emphasis>side</emphasis> - which side of the dialog to REFER. It can be:
+				'caller' or 'callee'.
 			</para>
 		</listitem>
 		<listitem>
@@ -1416,7 +1436,7 @@ dlg_bye("all");
 		<title><function>dlg_refer</function> usage</title>
 		<programlisting format="linespecific">
 ...
-dlg_refer("caller", "sip:[email protected]");
+dlg_refer("caller", "sip:announ[email protected]");
 ...
 </programlisting>
 		</example>
@@ -1427,7 +1447,7 @@ dlg_refer("caller", "sip:[email protected]");
 		<function moreinfo="none">dlg_manage()</function>
 		</title>
 		<para>
-		Process current SIP request with dialog module. It is alternative to
+		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>
@@ -1954,7 +1974,7 @@ if(!uri == myself) {
 		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.
+		support values, the value parameter will be silently discarded.
 		</para>
 		<para>Name: <emphasis>dlg.profile_get_size</emphasis></para>
 		<para>Parameters:</para>
@@ -1979,7 +1999,7 @@ if(!uri == myself) {
 		<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
+		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.
@@ -2005,7 +2025,7 @@ if(!uri == myself) {
 		<section>
 		<title><varname>dlg.bridge_dlg</varname></title>
 		<para>
-			Bridge two SIP addresses in a call using INVITE(hold)-REFER-BYE
+			Bridge two SIP addresses into a call using INVITE(hold)-REFER-BYE
 			mechanism.
 		</para>
 		<para>Name: <emphasis>dlg.bridge_dlg</emphasis></para>