- port from opensips, r4516, credits goes to Bogdan-Andrei Iancu

- new function added : unset_dlg_profile() - removes the dialog from a profile; This functionality is very useful if you have scenarios with serial forking and the profile is related to the destination.


git-svn-id: https://openser.svn.sourceforge.net/svnroot/openser/trunk@4580 689a6050-402a-0410-94f2-e92a70836424

modules_k/dialog/README

@@ -1,3 +1,4 @@
+
 dialog Module
 
 Bogdan-Andrei Iancu
@@ -10,9 +11,9 @@ Bogdan-Andrei Iancu
 
    Copyright © 2006 voice-system.ro
    Revision History
-   Revision $Revision$ $Date: 2008-03-19 21:31:30 +0200
-                              (Wed, 19 Mar 2008) $
-     __________________________________________________________
+   Revision $Revision$ $Date: 2008-03-19 15:31:30 -0400
+   (Wed, 19 Mar 2008) $
+     _________________________________________________________
 
    Table of Contents
 
@@ -64,9 +65,10 @@ Bogdan-Andrei Iancu
 
         1.6. Exported Functions
 
-              1.6.1. set_dlg_profile(profile,[value])
-              1.6.2. is_in_profile(profile,[value])
-              1.6.3. get_profile_size(profile,[value],size)
+              1.6.1. set_dlg_profile(profile,[value]) 
+              1.6.2. unset_dlg_profile(profile,[value]) 
+              1.6.3. is_in_profile(profile,[value]) 
+              1.6.4. get_profile_size(profile,[value],size) 
 
         1.7. Exported statistics
 
@@ -95,7 +97,7 @@ Bogdan-Andrei Iancu
         2.1. Available Functions
 
               2.1.1. register_dlgcb (dialog, type, cb, param,
-                      free_param_cb)
+                      free_param_cb) 
 
    3. Frequently Asked Questions
 
@@ -135,8 +137,9 @@ Bogdan-Andrei Iancu
    1.32. Set profiles_with_value parameter
    1.33. Set profiles_no_value parameter
    1.34. set_dlg_profile usage
-   1.35. is_in_profile usage
-   1.36. get_profile_size usage
+   1.35. unset_dlg_profile usage
+   1.36. is_in_profile usage
+   1.37. get_profile_size usage
 
 Chapter 1. Admin Guide
 
@@ -144,26 +147,27 @@ Chapter 1. Admin Guide
 
    The dialog module provides dialog awareness to the Kamailio
    proxy. Its functionality is to keep trace of the current
-   dialogs, to offer information about them (like how many dialogs
-   are active). The module exports no functions that could be used
-   directly from scripts.
+   dialogs, to offer information about them (like how many
+   dialogs are active). The module exports no functions that
+   could be used directly from scripts.
 
-   The module, via an internal API, also provide the foundation to
-   build on top of it more complex dialog-based functionalities
-   via other Kamailio modules.
+   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.
 
 1.2. How it works
 
-   To create the dialog associated to an initial request, the flag
-   "dlg_flag" (Section 1.5.4, "dlg_flag (integer)") must be set
-   before creating the corresponding transaction.
+   To create the dialog associated to an initial request, the
+   flag "dlg_flag" (Section 1.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 1.5.6,
-   "default_timeout (integer)") and custom timeout (see
-   "timeout_avp" - Section 1.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 1.5.6, "default_timeout (integer)") and custom timeout
+   (see "timeout_avp" - Section 1.5.5, "timeout_avp (string)").
+   The dialog timeout is reset each time a sequential request
+   passes.
 
 1.3. Dialog profiling
 
@@ -176,20 +180,20 @@ Chapter 1. Admin Guide
    the domain, dialogs terminated to 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 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.
+     * 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 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.
 
    A dialog can be added to multiple profiles in 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 the original request.
+   initial and sequential requests) and in the branch, failure
+   and reply routes of the original request.
 
 1.4. Dependencies
 
@@ -214,7 +218,7 @@ Chapter 1. Admin Guide
    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
 ...
@@ -223,9 +227,9 @@ modparam("dialog", "enable_stats", 0)
 
 1.5.2. hash_size (integer)
 
-   The size of the hash table internally used to keep the dialogs.
-   A larger table is much faster but consumes more memory. The
-   hash size must be a power of 2 number.
+   The size of the hash table internally used to keep the
+   dialogs. A larger table is much faster but consumes more
+   memory. The hash size must be a power of 2 number.
 
    IMPORTANT: If dialogs' information should be stored in a
    database, a constant hash_size should be used, otherwise the
@@ -233,7 +237,7 @@ modparam("dialog", "enable_stats", 0)
    modify the hash_size you must delete all table's rows before
    restarting openser.
 
-   Default value is "4096".
+   Default value is "4096". 
 
    Example 1.2. Set hash_size parameter
 ...
@@ -246,7 +250,7 @@ modparam("dialog", "hash_size", 1024)
    cookie. It is used for fast dialog matching of the sequential
    requests.
 
-   Default value is "did".
+   Default value is "did". 
 
    Example 1.3. Set rr_param parameter
 ...
@@ -256,9 +260,10 @@ modparam("dialog", "rr_param", "xyz")
 1.5.4. dlg_flag (integer)
 
    Flag to be used for marking if a dialog should be constructed
-   for the current request (make sense only for initial requests).
+   for the current request (make sense only for initial
+   requests).
 
-   Default value is "none".
+   Default value is "none". 
 
    Example 1.4. Set dlg_flag parameter
 ...
@@ -271,7 +276,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
 ...
@@ -283,7 +288,7 @@ modparam("dialog", "timeout_avp", "$avp(i:10)")
    The default dialog timeout (in seconds) if no custom one is
    set.
 
-   Default value is "43200 (12 hours)".
+   Default value is "43200 (12 hours)". 
 
    Example 1.6. Set default_timeout parameter
 ...
@@ -296,7 +301,7 @@ modparam("dialog", "default_timeout", 21600)
    to be added in the requests generated by the module (like
    BYEs).
 
-   Default value is "NULL".
+   Default value is "NULL". 
 
    Example 1.7. Set dlf_extra_hdrs parameter
 ...
@@ -317,7 +322,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
 ...
@@ -329,12 +334,13 @@ modparam("dialog", "dlg_match_mode", 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://openser:openserrw@localhost/openser". 
 
    Example 1.9. Set db_url parameter
 ...
-modparam("dialog", "db_url", "dbdriver://username:password@dbhost/dbname
-")
+modparam("dialog", "db_url", "dbdriver://username:password@dbhost/dbnam
+e")
 ...
 
 1.5.10. db_mode (integer)
@@ -351,7 +357,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.10. Set db_mode parameter
 ...
@@ -365,7 +371,7 @@ modparam("dialog", "db_mode", 1)
    too short interval will generate intensiv database operations,
    a too large one will not notice short dialogs.
 
-   Default value is "60".
+   Default value is "60". 
 
    Example 1.11. Set db_update_period parameter
 ...
@@ -374,14 +380,14 @@ modparam("dialog", "db_update_period", 120)
 
 1.5.12. db_fetch_rows (integer)
 
-   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.
+   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.
 
-   Default value is "200".
+   Default value is "200". 
 
    Example 1.12. Set db_fetch_rows parameter
 ...
@@ -393,7 +399,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.13. Set table_name parameter
 ...
@@ -402,9 +408,10 @@ modparam("dialog", "table_name", "my_dialog")
 
 1.5.14. callid_column (string)
 
-   The column's name in the database to store the dialogs' callid.
+   The column's name in the database to store the dialogs'
+   callid.
 
-   Default value is "callid".
+   Default value is "callid". 
 
    Example 1.14. Set callid_column parameter
 ...
@@ -416,7 +423,7 @@ modparam("dialog", "callid_column", "callid_c_name")
    The column's name in the database to store the caller's sip
    address.
 
-   Default value is "from_uri".
+   Default value is "from_uri". 
 
    Example 1.15. Set from_uri_column parameter
 ...
@@ -428,7 +435,7 @@ modparam("dialog", "from_uri_column", "from_uri_c_name")
    The column's 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.16. Set from_tag_column parameter
 ...
@@ -440,7 +447,7 @@ modparam("dialog", "from_tag_column", "from_tag_c_name")
    The column's name in the database to store the calee's sip
    address.
 
-   Default value is "to_uri".
+   Default value is "to_uri". 
 
    Example 1.17. Set to_uri_column parameter
 ...
@@ -452,7 +459,7 @@ modparam("dialog", "to_uri_column", "to_uri_c_name")
    The column's 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.18. Set to_tag_column parameter
 ...
@@ -461,10 +468,10 @@ modparam("dialog", "to_tag_column", "to_tag_c_name")
 
 1.5.19. caller_cseq_column (string)
 
-   The column's name in the database to store the cseq from caller
-   side.
+   The column's name in the database to store the cseq from
+   caller side.
 
-   Default value is "caller_cseq".
+   Default value is "caller_cseq". 
 
    Example 1.19. Set caller_cseq_column parameter
 ...
@@ -473,10 +480,10 @@ modparam("dialog", "caller_cseq_column", "column_name")
 
 1.5.20. callee_cseq_column (string)
 
-   The column's name in the database to store the cseq from callee
-   side.
+   The column's name in the database to store the cseq from
+   callee side.
 
-   Default value is "callee_cseq".
+   Default value is "callee_cseq". 
 
    Example 1.20. Set callee_cseq_column parameter
 ...
@@ -488,7 +495,7 @@ modparam("dialog", "callee_cseq_column", "column_name")
    The column's 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.21. Set caller_route_column parameter
 ...
@@ -500,7 +507,7 @@ modparam("dialog", "caller_route_column", "column_name")
    The column's 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.22. Set to_route_column parameter
 ...
@@ -509,10 +516,10 @@ modparam("dialog", "to_route_column", "column_name")
 
 1.5.23. caller_contact_column (string)
 
-   The column's name in the database to store the caller's contact
-   uri.
+   The column's name in the database to store the caller's
+   contact uri.
 
-   Default value is "from_contact".
+   Default value is "from_contact". 
 
    Example 1.23. Set caller_contact_column parameter
 ...
@@ -521,10 +528,10 @@ modparam("dialog", "caller_contact_column", "column_name")
 
 1.5.24. callee_contact_column (string)
 
-   The column's name in the database to store the callee's contact
-   uri.
+   The column's name in the database to store the callee's
+   contact uri.
 
-   Default value is "callee_contact".
+   Default value is "callee_contact". 
 
    Example 1.24. Set callee_contact_column parameter
 ...
@@ -536,7 +543,7 @@ modparam("dialog", "callee_contact_column", "column_name")
    The column's 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.25. Set caller_sock_column parameter
 ...
@@ -548,7 +555,7 @@ modparam("dialog", "caller_sock_column", "column_name")
    The column's 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.26. Set callee_sock_column parameter
 ...
@@ -557,10 +564,10 @@ modparam("dialog", "callee_sock_column", "column_name")
 
 1.5.27. h_id_column (string)
 
-   The column's name in the database to store the dialogs' hash id
-   information.
+   The column's name in the database to store the dialogs' hash
+   id information.
 
-   Default value is "hash_id".
+   Default value is "hash_id". 
 
    Example 1.27. Set h_id_column parameter
 ...
@@ -572,7 +579,7 @@ modparam("dialog", "h_id_column", "hash_id_c_name")
    The column's name in the database to store the dialogs' hash
    entry information.
 
-   Default value is "hash_entry".
+   Default value is "hash_entry". 
 
    Example 1.28. Set h_entry_column parameter
 ...
@@ -584,7 +591,7 @@ modparam("dialog", "h_entry_column", "h_entry_c_name")
    The column's name in the database to store the dialogs' state
    information.
 
-   Default value is "state".
+   Default value is "state". 
 
    Example 1.29. Set state_column parameter
 ...
@@ -596,7 +603,7 @@ modparam("dialog", "state_column", "state_c_name")
    The column's name in the database to store the dialogs' start
    time information.
 
-   Default value is "start_time".
+   Default value is "start_time". 
 
    Example 1.30. Set start_time_column parameter
 ...
@@ -608,7 +615,7 @@ modparam("dialog", "start_time_column", "start_time_c_name")
    The column's name in the database to store the dialogs'
    timeout.
 
-   Default value is "timeout".
+   Default value is "timeout". 
 
    Example 1.31. Set timeout_column parameter
 ...
@@ -619,7 +626,7 @@ modparam("dialog", "timeout_column", "timeout_c_name")
 
    List of names for profiles with values.
 
-   Default value is "empty".
+   Default value is "empty". 
 
    Example 1.32. Set profiles_with_value parameter
 ...
@@ -630,7 +637,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.33. Set profiles_no_value parameter
 ...
@@ -661,14 +668,33 @@ set_dlg_profile("inbound_call");
 set_dlg_profile("caller","$fu");
 ...
 
-1.6.2.  is_in_profile(profile,[value])
+1.6.2.  unset_dlg_profile(profile,[value])
+
+   Removes the current dialog from a profile.
+
+   Meaning of the parameters is as follows:
+     * profile - name of the profile to be removed from;
+     * value (optional) - string value to define the belonging of
+       the dialog to the profile - note that the profile must
+       support values. Pseudo-variables are supported.
+
+   This function can be used from BRANCH_ROUTE, REPLY_ROUTE and
+   FAILURE_ROUTE.
+
+   Example 1.35. unset_dlg_profile usage
+...
+unset_dlg_profile("inbound_call");
+unset_dlg_profile("caller","$fu");
+...
+
+1.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 not value is passed, only
-   simply belonging of the dialog to the profile is checked. Note
-   that the profile does not supports values, this will be
+   into account a specific value - if the dialog was inserted
+   into the profile for a specific value. If not value is passed,
+   only simply belonging of the dialog to the profile is checked.
+   Note that the profile does not supports values, this will be
    silently discarded.
 
    Meaning of the parameters is as follows:
@@ -679,7 +705,7 @@ set_dlg_profile("caller","$fu");
    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE,
    REPLY_ROUTE and FAILURE_ROUTE.
 
-   Example 1.35. is_in_profile usage
+   Example 1.36. is_in_profile usage
 ...
 if (is_in_profile("inbound_call")) {
         log("this request belongs to a inbound call\n");
@@ -690,27 +716,27 @@ if (is_in_profile("caller","XX")) {
 }
 ...
 
-1.6.3.  get_profile_size(profile,[value],size)
+1.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 not value is passed,
-   only simply belonging of the dialog to the profile is checked.
-   Note that the profile does not supports values, this will be
-   silently discarded.
+   into the profile with a specific value. If not value is
+   passed, only simply belonging of the dialog to the profile is
+   checked. Note that the profile does not supports values, this
+   will be silently discarded.
 
    Meaning of the parameters is as follows:
      * profile - name of the profile to get the size for;
      * value (optional) - string value to toughen the check.
        Pseudo-variables are supported;
-     * size - an AVP or script variable to return the profile size
-       in.
+     * size - an AVP or script variable to return the profile
+       size in.
 
    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE,
    REPLY_ROUTE and FAILURE_ROUTE.
 
-   Example 1.36. get_profile_size usage
+   Example 1.37. get_profile_size usage
 ...
 get_profile_size("inbound_call","$avp(size)");
 xlog("currently there are $avp(size) inbound calls\n");
@@ -747,14 +773,15 @@ xlog("currently, the user %fu has $avp(size) active outgoing calls\n");
 
 1.8.1. dlg_list
 
-   Lists the description of a dialog or of all dialogs (calls). If
-   only one dialogs is to be listed, the dialog identifiers are to
-   be passed as paramter (callid and fromtag).
+   Lists the description of a dialog or of all dialogs (calls).
+   If only one dialogs is to be listed, the dialog identifiers
+   are to be passed as paramter (callid and fromtag).
 
    Name: dlg_list
 
    Parameters:
-     * callid (optional) - callid if a single dialog to be listed.
+     * callid (optional) - callid if a single dialog to be
+       listed.
      * from_tag (optional, but cannot be present without the
        callid paramter) - fromtag (as per initial request) of the
        dialog to be listed. entry
@@ -762,8 +789,7 @@ xlog("currently, the user %fu has $avp(size) active outgoing calls\n");
    MI FIFO Command Format:
                 :dlg_list:_reply_fifo_file_
                 _empty_line_
-
-                :dlg_list:_reply_fifo_file_
+                                :dlg_list:_reply_fifo_file_
                 [email protected]
                 AAdfeEFF33
 
@@ -783,7 +809,8 @@ xlog("currently, the user %fu has $avp(size) active outgoing calls\n");
 
 1.8.3. dlg_end_dlg
 
-   Terminates an ongoing dialog by sending BYE in both directions.
+   Terminates an ongoing dialog by sending BYE in both
+   directions.
 
    Name: dlg_end_dlg
 
@@ -791,11 +818,11 @@ xlog("currently, the user %fu has $avp(size) active outgoing calls\n");
      * h_entry - hash entry of the dialog in the internal dialog
        table
      * h_id - hash id of the dialog on the hash entry
-     * extra_hdrs - (optional) string containg extra headers (full
-       format) to be added to the BYE requests.
+     * extra_hdrs - (optional) string containg extra headers
+       (full format) to be added to the BYE requests.
 
-   The values for the h_entry and h_id can be get via the dlg_list
-   MI command.
+   The values for the h_entry and h_id can be get via the
+   dlg_list MI command.
 
    MI FIFO Command Format:
                 :dlg_end_dlg:_reply_fifo_file_
@@ -808,10 +835,10 @@ xlog("currently, the user %fu has $avp(size) active outgoing calls\n");
    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 not value is passed,
-   only simply belonging of the dialog to the profile is checked.
-   Note that the profile does not supports values, this will be
-   silently discarded.
+   into the profile with a specific value. If not value is
+   passed, only simply belonging of the dialog to the profile is
+   checked. Note that the profile does not supports values, this
+   will be silently discarded.
 
    Name: profile_get_size
 
@@ -854,9 +881,9 @@ xlog("currently, the user %fu has $avp(size) active outgoing calls\n");
 
 1.9.2. $DLG_status
 
-   Returns the status of the dialog corresponding to the processed
-   sequential request. This PV will be available only for
-   sequential requests, after doing loose_route().
+   Returns the status of the dialog corresponding to the
+   processed sequential request. This PV will be available only
+   for sequential requests, after doing loose_route().
 
    Value may be:
      * NULL - Dialog not found.
@@ -867,10 +894,10 @@ xlog("currently, the user %fu has $avp(size) active outgoing calls\n");
 1.9.3. $DLG_lifetime
 
    Returns the duration (in seconds) of the dialog corresponding
-   to the processed sequential request. The duration is calculated
-   from the dialog confirmation and the current moment. This PV
-   will be available only for sequential requests, after doing
-   loose_route().
+   to the processed sequential request. The duration is
+   calculated from the dialog confirmation and the current
+   moment. This PV will be available only for sequential
+   requests, after doing loose_route().
 
    NULL will be returned if there is no dialog for the request.
 
@@ -884,8 +911,8 @@ Chapter 2. Developer Guide
 
    Meaning of the parameters is as follows:
      * struct dlg_cell* dlg - dialog to register callback to. If
-       maybe NULL only for DLG_CREATED callback type, which is not
-       a per dialog type.
+       maybe NULL only for DLG_CREATED callback type, which is
+       not a per dialog type.
      * int type - types of callbacks; more types may be register
        for the same callback function; only DLG_CREATED must be
        register alone. Possible types:
@@ -907,9 +934,9 @@ Chapter 2. Developer Guide
           + DLGCB_RESPONSE_FWDED - called when the dialog matches
             a reply to the initial INVITE request - it's a per
             dialog type.
-          + DLGCB_RESPONSE_WITHIN - called when the dialog matches
-            a reply to a subsequent in dialog request - it's a per
-            dialog type.
+          + DLGCB_RESPONSE_WITHIN - called when the dialog
+            matches a reply to a subsequent in dialog request -
+            it's a per dialog type.
           + DLGCB_MI_CONTEXT - called when the mi dlg_list_ctx
             command is invoked - it's a per dialog type.
           + DLGCB_DESTROY
@@ -926,39 +953,37 @@ Chapter 3. Frequently Asked Questions
 
    3.1.
 
-       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).
+   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).
    3.2.
 
-       Where can I find more about Kamailio?
-
-       Take a look at http://www.kamailio.org/.
+   Where can I find more about Kamailio?
 
+   Take a look at http://www.kamailio.org/.
    3.3.
 
-       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.kamailio.org/cgi-bin/mailman/listinfo/users
-         * Developer Mailing List -
-           http://lists.kamailio.org/cgi-bin/mailman/listinfo/devel
+   Where can I post a question about this module?
 
-       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]>.
+   First at all check if your question was already answered on
+   one of our mailing lists:
+     * User Mailing List -
+       http://lists.kamailio.org/cgi-bin/mailman/listinfo/users
+     * Developer Mailing List -
+       http://lists.kamailio.org/cgi-bin/mailman/listinfo/devel
 
-       If you want to keep the mail private, send it 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]>.
    3.4.
 
-       How can I report a bug?
+   How can I report a bug?
 
-       Please follow the guidelines provided at:
-       http://sourceforge.net/tracker/?group_id=139143.
+   Please follow the guidelines provided at:
+   http://sourceforge.net/tracker/?group_id=139143.

modules_k/dialog/dialog.c

@@ -108,6 +108,7 @@ static int fixup_profile(void** param, int param_no);
 static int fixup_get_profile2(void** param, int param_no);
 static int fixup_get_profile3(void** param, int param_no);
 static int w_set_dlg_profile(struct sip_msg*, char*, char*);
+static int w_unset_dlg_profile(struct sip_msg*, char*, char*);
 static int w_is_in_profile(struct sip_msg*, char*, char*);
 static int w_get_profile_size(struct sip_msg*, char*, char*, char*);
 
@@ -117,6 +118,10 @@ static cmd_export_t cmds[]={
 			0, REQUEST_ROUTE| FAILURE_ROUTE | ONREPLY_ROUTE | BRANCH_ROUTE },
 	{"set_dlg_profile", (cmd_function)w_set_dlg_profile,  2,fixup_profile,
 			0, REQUEST_ROUTE| FAILURE_ROUTE | ONREPLY_ROUTE | BRANCH_ROUTE },
+	{"unset_dlg_profile", (cmd_function)w_unset_dlg_profile,  1,fixup_profile,
+			0, FAILURE_ROUTE | ONREPLY_ROUTE | BRANCH_ROUTE },
+	{"unset_dlg_profile", (cmd_function)w_unset_dlg_profile,  2,fixup_profile,
+			0, FAILURE_ROUTE | ONREPLY_ROUTE | BRANCH_ROUTE },
 	{"is_in_profile", (cmd_function)w_is_in_profile,      1,fixup_profile,
 			0, REQUEST_ROUTE| FAILURE_ROUTE | ONREPLY_ROUTE | BRANCH_ROUTE },
 	{"is_in_profile", (cmd_function)w_is_in_profile,      2,fixup_profile,
@@ -552,6 +557,37 @@ static int w_set_dlg_profile(struct sip_msg *msg, char *profile, char *value)
 }
 
 
+
+static int w_unset_dlg_profile(struct sip_msg *msg, char *profile, char *value)
+{
+	pv_elem_t *pve;
+	str val_s;
+
+	pve = (pv_elem_t *)value;
+
+	if (((struct dlg_profile_table*)profile)->has_value) {
+		if ( pve==NULL || pv_printf_s(msg, pve, &val_s)!=0 || 
+		val_s.len == 0 || val_s.s == NULL) {
+			LM_WARN("cannot get string for value\n");
+			return -1;
+		}
+		if ( unset_dlg_profile( msg, &val_s,
+		(struct dlg_profile_table*)profile) < 0 ) {
+			LM_ERR("failed to unset profile");
+			return -1;
+		}
+	} else {
+		if ( unset_dlg_profile( msg, NULL,
+		(struct dlg_profile_table*)profile) < 0 ) {
+			LM_ERR("failed to unset profile");
+			return -1;
+		}
+	}
+	return 1;
+}
+
+
+
 static int w_is_in_profile(struct sip_msg *msg, char *profile, char *value)
 {
 	pv_elem_t *pve;

modules_k/dialog/dlg_profile.c

@@ -414,6 +414,59 @@ int set_dlg_profile(struct sip_msg *msg, str *value,
 }
 
 
+int unset_dlg_profile(struct sip_msg *msg, str *value,
+									struct dlg_profile_table *profile)
+{
+	struct dlg_cell *dlg;
+	struct dlg_profile_link *linker;
+	struct dlg_profile_link *linker_prev;
+	struct dlg_entry *d_entry;
+
+	/* get current dialog */
+	dlg = get_current_dialog(msg);
+
+	if (dlg==NULL || route_type==REQUEST_ROUTE) {
+		LM_CRIT("BUG - dialog NULL or del_profile used in request route\n");
+		return -1;
+	}
+
+	/* check the dialog linkers */
+	d_entry = &d_table->entries[dlg->h_entry];
+	dlg_lock( d_table, d_entry);
+	linker = dlg->profile_links;
+	linker_prev = NULL;
+	for( ; linker ; linker_prev=linker,linker=linker->next) {
+		if (linker->profile==profile) {
+			if (profile->has_value==0) {
+				goto found;
+			} else if (value && value->len==linker->hash_linker.value.len &&
+			memcmp(value->s,linker->hash_linker.value.s,value->len)==0){
+				goto found;
+			}
+			dlg_unlock( d_table, d_entry);
+			return -1;
+		}
+	}
+	dlg_unlock( d_table, d_entry);
+	return -1;
+
+found:
+	/* table still locked */
+	/* remove the linker element from dialog */
+	if (linker_prev==NULL) {
+		dlg->profile_links = linker->next;
+	} else {
+		linker_prev->next = linker->next;
+	}
+	linker->next = NULL;
+	dlg_unlock( d_table, d_entry);
+	/* remove linker from profile table and free it */
+	destroy_linkers(linker);
+	return 1;
+}
+
+
+
 int is_dlg_in_profile(struct sip_msg *msg, struct dlg_profile_table *profile,
 																str *value)
 {

modules_k/dialog/dlg_profile.h

@@ -82,6 +82,9 @@ void set_current_dialog(struct sip_msg *msg, struct dlg_cell *dlg);
 int set_dlg_profile(struct sip_msg *msg, str *value,
 		struct dlg_profile_table *profile);
 
+int unset_dlg_profile(struct sip_msg *msg, str *value,
+		struct dlg_profile_table *profile);
+
 int is_dlg_in_profile(struct sip_msg *msg, struct dlg_profile_table *profile,
 		str *value);
 

modules_k/dialog/doc/dialog_admin.xml

@@ -903,6 +903,44 @@ set_dlg_profile("caller","$fu");
 		</example>
 	</section>
 
+	<section>
+		<title>
+		<function moreinfo="none">unset_dlg_profile(profile,[value])</function>
+		</title>
+		<para>
+		Removes the current dialog from a profile.
+		</para>
+		<para>Meaning of the parameters is as follows:</para>
+		<itemizedlist>
+		<listitem>
+			<para><emphasis>profile</emphasis> - name of the profile to be 
+			removed from;
+			</para>
+		</listitem>
+		<listitem>
+			<para><emphasis>value</emphasis> (optional) - string value to 
+			define the belonging of the dialog to the profile - note that the
+			profile must support values.
+			Pseudo-variables are supported.
+			</para>
+		</listitem>
+		</itemizedlist>
+		<para>
+		This function can be used from BRANCH_ROUTE,
+			REPLY_ROUTE and FAILURE_ROUTE.
+		</para>
+		<example>
+		<title><function>unset_dlg_profile</function> usage</title>
+		<programlisting format="linespecific">
+...
+unset_dlg_profile("inbound_call");
+unset_dlg_profile("caller","$fu");
+...
+</programlisting>
+		</example>
+	</section>
+
+
 	<section>
 		<title>
 		<function moreinfo="none">is_in_profile(profile,[value])</function>