dialog(k): Added dlg_set_timeout_by_profile() route script function.

This function allows the same dialog timeout to be set across all
the dialogs in a profile (with or without values).

The intended use-case is to allow the user to conditionally end or
expire from tracking a user's/caller's/account's calls.

modules_k/dialog/README

@@ -22,9 +22,9 @@ Alex Balashov
 
    <[email protected]>
 
-   Copyright © 2006 Voice Sistem SRL
+   Copyright © 2006 Voice Sistem SRL
 
-   Copyright © 2011 Carsten Bock, http://www.ng-voice.com
+   Copyright © 2011 Carsten Bock, http://www.ng-voice.com
      __________________________________________________________________
 
    Table of Contents
@@ -105,7 +105,8 @@ Alex Balashov
               6.12. dlg_get(callid, ftag, ttag)
               6.13. is_known_dlg()
               6.14. dlg_set_timeout(timeout [, h_entry, h_id])
-              6.15. dlg_set_property(attr)
+              6.15. dlg_set_timeout_by_profile(profile, [value], timeout)
+              6.16. dlg_set_property(attr)
 
         7. Statistics
 
@@ -224,7 +225,8 @@ Alex Balashov
    1.59. dlg_get usage
    1.60. is_known_dlg() usage
    1.61. dlg_set_timeout usage
-   1.62. dlg_set_property usage
+   1.62. dlg_set_timeout_by_profile usage
+   1.63. dlg_set_property usage
 
 Chapter 1. Admin Guide
 
@@ -304,7 +306,8 @@ Chapter 1. Admin Guide
         6.12. dlg_get(callid, ftag, ttag)
         6.13. is_known_dlg()
         6.14. dlg_set_timeout(timeout [, h_entry, h_id])
-        6.15. dlg_set_property(attr)
+        6.15. dlg_set_timeout_by_profile(profile, [value], timeout)
+        6.16. dlg_set_property(attr)
 
    7. Statistics
 
@@ -378,14 +381,14 @@ Chapter 1. Admin Guide
 2. How it works
 
    To create the dialog associated with an initial request, the flag
-   "dlg_flag" (Section 5.4, "dlg_flag (integer)") must be set before
+   “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
+   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
@@ -491,7 +494,7 @@ Chapter 1. Admin Guide
    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
 ...
@@ -509,7 +512,7 @@ modparam("dialog", "enable_stats", 0)
    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
 ...
@@ -522,7 +525,7 @@ modparam("dialog", "hash_size", 1024)
    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
 ...
@@ -534,7 +537,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
 ...
@@ -547,7 +550,7 @@ modparam("dialog", "dlg_flag", 4)
    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
 ...
@@ -559,7 +562,7 @@ modparam("dialog", "timeout_avp", "$avp(i:10)")
    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
 ...
@@ -571,7 +574,7 @@ modparam("dialog", "default_timeout", 21600)
    A string containing the extra headers (full format, with EOH) to be
    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
 ...
@@ -592,7 +595,7 @@ modparam("dialog", "dlg_extra_hdrs", "Hint: credit expired\r\n")
      * 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
 ...
@@ -621,7 +624,7 @@ modparam("dialog", "detect_spirals", 1)
    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://kamailio:kamailiorw@localhost/kamailio�.
 
    Example 1.10. Set db_url parameter
 ...
@@ -642,7 +645,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
 ...
@@ -656,7 +659,7 @@ modparam("dialog", "db_mode", 1)
    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
 ...
@@ -672,7 +675,7 @@ modparam("dialog", "db_update_period", 120)
    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
 ...
@@ -684,7 +687,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
 ...
@@ -695,7 +698,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
 ...
@@ -706,7 +709,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
 ...
@@ -718,7 +721,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
 ...
@@ -729,7 +732,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
 ...
@@ -741,7 +744,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
 ...
@@ -752,7 +755,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
 ...
@@ -763,7 +766,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
 ...
@@ -775,7 +778,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
 ...
@@ -787,7 +790,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
 ...
@@ -798,7 +801,7 @@ modparam("dialog", "callee_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
 ...
@@ -809,7 +812,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
 ...
@@ -821,7 +824,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
 ...
@@ -833,7 +836,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
 ...
@@ -845,7 +848,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
 ...
@@ -857,7 +860,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
 ...
@@ -869,7 +872,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
 ...
@@ -881,7 +884,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
 ...
@@ -892,7 +895,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
 ...
@@ -903,7 +906,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
 ...
@@ -915,7 +918,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
 ...
@@ -927,7 +930,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
 ...
@@ -939,7 +942,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
 ...
@@ -951,7 +954,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
 ...
@@ -962,7 +965,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
 ...
@@ -973,7 +976,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
 ...
@@ -984,7 +987,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
 ...
@@ -995,7 +998,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
 ...
@@ -1006,7 +1009,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
 ...
@@ -1029,7 +1032,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
 ...
@@ -1041,7 +1044,7 @@ modparam("dialog", "initial_cbs_inscript", 0)
    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.
 
-   Default value is "0".
+   Default value is “0�.
 
    Example 1.44. Set send_bye parameter
 ...
@@ -1055,7 +1058,7 @@ modparam("dialog", "send_bye", 1)
    is destroyed when negative reply is sent out (less internal
    complexity).
 
-   Default value is "1".
+   Default value is “1�.
 
    Example 1.45. Set wait_ack parameter
 ...
@@ -1068,7 +1071,7 @@ modparam("dialog", "wait_ack", 0)
    dialog keep alives (SIP OPTIONS requests within dialog). The value
    represents the number of seconds.
 
-   Default value is "0" (no keep alive).
+   Default value is “0� (no keep alive).
 
    Example 1.46. Set ka_timer parameter
 ...
@@ -1083,7 +1086,7 @@ modparam("dialog", "ka_timer", 10)
    dialog setup or previous keep-alive. The value represents the number of
    seconds.
 
-   Default value is "0" (no keep alive).
+   Default value is “0� (no keep alive).
 
    Example 1.47. Set ka_interval parameter
 ...
@@ -1106,9 +1109,10 @@ modparam("dialog", "ka_interval", 300)
    6.12. dlg_get(callid, ftag, ttag)
    6.13. is_known_dlg()
    6.14. dlg_set_timeout(timeout [, h_entry, h_id])
-   6.15. dlg_set_property(attr)
+   6.15. dlg_set_timeout_by_profile(profile, [value], timeout)
+   6.16. dlg_set_property(attr)
 
-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 support values, they will be silently discarded. Also, there
@@ -1130,7 +1134,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.
 
@@ -1149,7 +1153,7 @@ 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
@@ -1177,7 +1181,7 @@ 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
@@ -1204,7 +1208,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.
 
@@ -1222,7 +1226,7 @@ if(dlg_isflagset("1"))
 }
 ...
 
-6.6. dlg_setflag(flag)
+6.6.  dlg_setflag(flag)
 
    Set the dialog flag.
 
@@ -1237,7 +1241,7 @@ if(dlg_isflagset("1"))
 dlg_setflag("1");
 ...
 
-6.7. dlg_resetflag(flag)
+6.7.  dlg_resetflag(flag)
 
    Reset the dialog flag.
 
@@ -1252,7 +1256,7 @@ dlg_setflag("1");
 redlg_setflag("1");
 ...
 
-6.8. dlg_bye(side)
+6.8.  dlg_bye(side)
 
    Send BYE to both parties of a dialog.
 
@@ -1268,7 +1272,7 @@ 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'.
 
@@ -1285,7 +1289,7 @@ dlg_bye("all");
 dlg_refer("caller", "sip:[email protected]");
 ...
 
-6.10. dlg_manage()
+6.10.  dlg_manage()
 
    Process current SIP request with dialog module. It is an alternative to
    setting dialog flag for initial INVITE and Route-parameter-callback
@@ -1309,13 +1313,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,
@@ -1327,7 +1331,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.
@@ -1348,7 +1352,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
@@ -1373,7 +1377,7 @@ if(!uri == myself) {
 }
 ...
 
-6.14. dlg_set_timeout(timeout [, h_entry, h_id])
+6.14.  dlg_set_timeout(timeout [, h_entry, h_id])
 
    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
@@ -1396,7 +1400,29 @@ if(dlg_set_timeout("180", "123", "456"))
 }
 ...
 
-6.15. dlg_set_property(attr)
+6.15.  dlg_set_timeout_by_profile(profile, [value], timeout)
+
+   Like dlg_set_timeout(), but simultaneously sets the timeout of all
+   dialogs in a given profile. Can be constrained by profile value.
+
+   Meaning of the parameters is as follows:
+     * profile - The dialog profile across which to apply the timeout.
+       value (optional) - The profile value to use when applying the
+       dialog timeout.
+       timeout - the interval in seconds after which the dialog will time
+       out.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.62. dlg_set_timeout_by_profile usage
+...
+# 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");
+...
+
+6.16.  dlg_set_property(attr)
 
    Set a dialog property - an attribute that enable/disable various
    behaviours (e.g., sending keep alive requests).
@@ -1415,7 +1441,7 @@ if(dlg_set_timeout("180", "123", "456"))
 
    This function can be used from ANY_ROUTE.
 
-   Example 1.62. dlg_set_property usage
+   Example 1.63. dlg_set_property usage
 ...
 dlg_set_property("ka-src");
 dlg_set_property("ka-dst");
@@ -1485,12 +1511,12 @@ dlg_set_property("ka-dst");
 
 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_
@@ -1623,7 +1649,7 @@ dlg_set_property("ka-dst");
 
 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
@@ -1648,13 +1674,13 @@ dlg_set_property("ka-dst");
 
 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
@@ -1811,7 +1837,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.
 
@@ -1853,14 +1879,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
 
@@ -1871,46 +1897,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/dialog.c

@@ -164,6 +164,9 @@ static int w_dlg_bye(struct sip_msg*, char*, char*);
 static int w_dlg_refer(struct sip_msg*, char*, char*);
 static int w_dlg_bridge(struct sip_msg*, char*, char*, char*);
 static int w_dlg_set_timeout(struct sip_msg*, char*, char*, char*);
+static int w_dlg_set_timeout_by_profile2(struct sip_msg *, char *, char *);
+static int w_dlg_set_timeout_by_profile3(struct sip_msg *, char *, char *, 
+					char *);
 static int fixup_dlg_bye(void** param, int param_no);
 static int fixup_dlg_refer(void** param, int param_no);
 static int fixup_dlg_bridge(void** param, int param_no);
@@ -209,6 +212,12 @@ static cmd_export_t cmds[]={
 			0, ANY_ROUTE },
 	{"dlg_set_timeout", (cmd_function)w_dlg_set_timeout,  3,fixup_igp_all,
 			0, ANY_ROUTE },
+	{"dlg_set_timeout_by_profile", 
+		(cmd_function) w_dlg_set_timeout_by_profile2, 2, fixup_profile,
+			0, ANY_ROUTE },
+	{"dlg_set_timeout_by_profile", 
+		(cmd_function) w_dlg_set_timeout_by_profile3, 3, fixup_profile,
+			0, ANY_ROUTE },
 	{"dlg_set_property", (cmd_function)w_dlg_set_property,1,fixup_spve_null,
 			0, ANY_ROUTE },
 	{"load_dlg",  (cmd_function)load_dlg,   0, 0, 0, 0},
@@ -1124,14 +1133,9 @@ static int w_dlg_set_timeout(struct sip_msg *msg, char *pto, char *phe, char *ph
 		return -1;
 	}
 
-	if(update_dlg_timer(&dlg->tl, to)<0) {
-		LM_ERR("failed to update dialog lifetime\n");
-		dlg_release(dlg);
+	if(update_dlg_timeout(dlg, to) != 0) 
 		return -1;
-	}
-	dlg->lifetime = to;
-	dlg->dflags |= DLG_FLAG_CHANGED;
-	dlg_release(dlg);
+
 	return 1;
 }
 
@@ -1176,6 +1180,34 @@ static int w_dlg_set_property(struct sip_msg *msg, char *prop, char *s2)
 	return 1;
 }
 
+static int w_dlg_set_timeout_by_profile3(struct sip_msg *msg, char *profile,
+					char *value, char *timeout_str) 
+{
+	pv_elem_t *pve = NULL;
+	str val_s;
+
+	pve = (pv_elem_t *) value;
+
+	if(pve != NULL && ((struct dlg_profile_table *) profile)->has_value) {
+		if(pv_printf_s(msg,pve, &val_s) != 0 || 
+		   !val_s.s || val_s.len == 0) {
+			LM_WARN("cannot get string for value\n");
+			return -1;
+		}
+	}
+
+	if(dlg_set_timeout_by_profile((struct dlg_profile_table *) profile,
+				   &val_s, atoi(timeout_str)) != 0)
+		return -1;
+
+	return 1;
+}
+
+static int w_dlg_set_timeout_by_profile2(struct sip_msg *msg, 
+					 char *profile, char *timeout_str)
+{
+	return w_dlg_set_timeout_by_profile3(msg, profile, NULL, timeout_str);
+}
 
 void dlg_ka_timer_exec(unsigned int ticks, void* param)
 {

modules_k/dialog/dlg_hash.c

@@ -964,6 +964,27 @@ int dlg_set_toroute(struct dlg_cell *dlg, str *route)
 	return 0;
 }
 
+/*
+ * Internal function to adjust the lifetime of a dialog, used by
+ * various userland functions that touch the dialog timeout.
+ */
+
+int	update_dlg_timeout(dlg_cell_t *dlg, int timeout)
+{
+	if(update_dlg_timer(&dlg->tl, timeout) < 0) {
+		LM_ERR("failed to update dialog lifetime\n");
+		dlg_release(dlg);
+		return -1;
+	} 
+
+	dlg->lifetime = timeout;
+	dlg->dflags |= DLG_FLAG_CHANGED;
+
+	dlg_release(dlg);
+
+	return 0;
+}
+
 /**************************** MI functions ******************************/
 /*!
  * \brief Helper method that output a dialog via the MI interface

modules_k/dialog/dlg_hash.h

@@ -527,6 +527,12 @@ int dlg_ka_add(dlg_cell_t *dlg);
 
 int dlg_ka_run(ticks_t ti);
 
+/*!
+ * \brief Update dialog lifetime - for internal callers.
+ */
+
+int update_dlg_timeout(dlg_cell_t *, int);
+
 /*!
  * \brief Output a dialog via the MI interface
  * \param rpl MI node that should be filled

modules_k/dialog/dlg_profile.c

@@ -65,7 +65,7 @@ static dlg_profile_table_t *profiles = NULL;
 static dlg_profile_table_t* new_dlg_profile( str *name,
 		unsigned int size, unsigned int has_value);
 
-
+extern int update_dlg_timeout(dlg_cell_t *, int);
 
 /*!
  * \brief Add profile definitions to the global list
@@ -704,6 +704,74 @@ int	is_known_dlg(struct sip_msg *msg) {
 	return 1;
 }
 
+/*
+ * \brief Set the timeout of all the dialogs in a given profile, by value.
+ * \param profile The evaluated profile name.
+ * \param value The value constraint.
+ * \param timeout The dialog timeout to apply.
+ */
+
+int	dlg_set_timeout_by_profile(struct dlg_profile_table *profile, 
+				   str *value, int timeout) 
+{
+	unsigned int		i;
+	struct dlg_profile_hash	*ph = NULL;
+
+	/* If the profile has no value, iterate through every 
+	 * node and set its timeout.
+	 */
+
+	if(profile->has_value == 0 || value == NULL) {
+		lock_get(&profile->lock);
+
+		for(i = 0; i < profile->size; i ++) {
+			ph = profile->entries[i].first;
+
+			if(!ph) continue;
+			
+			do { 
+				if(update_dlg_timeout(ph->dlg, timeout) < 0) {
+					lock_release(&profile->lock);
+					return -1;
+				}
+
+				ph = ph->next;
+			} while(ph != profile->entries[i].first);
+		} 
+
+		lock_release(&profile->lock);
+	}
+
+	else {
+		i = calc_hash_profile(value, NULL, profile);
+
+		lock_get(&profile->lock);
+
+		ph = profile->entries[i].first;
+
+		if(ph) {
+			do { 
+				if(value->len == ph->value.len &&
+				   memcmp(value->s, ph->value.s, 
+					  value->len) == 0) {
+
+					if(update_dlg_timeout(ph->dlg, 
+							timeout) < 0) {
+						lock_release(&profile->lock);
+						return -1;
+					}
+				}
+			} while(ph != profile->entries[i].first);
+
+			ph = ph->next;
+		}
+
+		lock_release(&profile->lock);
+	}
+
+	return 0;
+}
+
 /****************************** MI commands *********************************/
 
 /*!

modules_k/dialog/dlg_profile.h

@@ -194,6 +194,12 @@ struct mi_root * mi_profile_list(struct mi_root *cmd_tree, void *param );
  */
 int is_known_dlg(sip_msg_t *msg);
 
+/*!
+ * \brief Adjust timeout in all dialogs within a profile.
+ */
+
+int dlg_set_timeout_by_profile(struct dlg_profile_table *, str *, int);
+
 /*!
  * \brief Add dialog to a profile
  * \param dlg dialog

modules_k/dialog/doc/dialog_admin.xml

@@ -1723,6 +1723,44 @@ if(dlg_set_timeout("180", "123", "456"))
 		</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>