modules_k/rr: updated README

modules_k/rr/README

@@ -31,48 +31,49 @@ Bogdan-Andrei Iancu
 
    1. Admin Guide
 
-        1. Overview
-        2. Dialog support
-        3. Dependencies
+        1.1. Overview
+        1.2. Dialog support
+        1.3. Dependencies
 
-              3.1. Kamailio Modules
-              3.2. External Libraries or Applications
+              1.3.1. Kamailio Modules
+              1.3.2. External Libraries or Applications
 
-        4. Parameters
+        1.4. Parameters
 
-              4.1. enable_full_lr (integer)
-              4.2. append_fromtag (integer)
-              4.3. enable_double_rr (integer)
-              4.4. add_username (integer)
-              4.5. enable_socket_mismatch_warning (integer)
+              1.4.1. enable_full_lr (integer)
+              1.4.2. append_fromtag (integer)
+              1.4.3. enable_double_rr (integer)
+              1.4.4. add_username (integer)
+              1.4.5. enable_socket_mismatch_warning (integer)
+              1.4.6. custom_user_avp (avp string)
 
-        5. Functions
+        1.5. Functions
 
-              5.1. loose_route()
-              5.2. record_route() and record_route(string)
-              5.3. record_route_preset(string [,string2])
-              5.4. record_route_advertised_address(address)
-              5.5. add_rr_param(param)
-              5.6. check_route_param(re)
-              5.7. is_direction(dir)
+              1.5.1. loose_route()
+              1.5.2. record_route() and record_route(string)
+              1.5.3. record_route_preset(string [,string2])
+              1.5.4. record_route_advertised_address(address)
+              1.5.5. add_rr_param(param)
+              1.5.6. check_route_param(re)
+              1.5.7. is_direction(dir)
 
-        6. Exported Pseudo Variables
+        1.6. Exported Pseudo Variables
 
-              6.1. $route_uri
+              1.6.1. $route_uri
 
    2. Developer Guide
 
-        1. Available Functions
+        2.1. Available Functions
 
-              1.1. record_route(string)
-              1.2. record_route_advertised_address(string)
-              1.3. add_rr_param( msg, param)
-              1.4. check_route_param( msg, re)
-              1.5. is_direction( msg, dir)
-              1.6. get_route_param( msg, name, val)
-              1.7. register_rrcb( callback, param)
+              2.1.1. record_route(string)
+              2.1.2. record_route_advertised_address(string)
+              2.1.3. add_rr_param( msg, param)
+              2.1.4. check_route_param( msg, re)
+              2.1.5. is_direction( msg, dir)
+              2.1.6. get_route_param( msg, name, val)
+              2.1.7. register_rrcb( callback, param)
 
-        2. Examples
+        2.2. Examples
 
    List of Examples
 
@@ -82,56 +83,26 @@ Bogdan-Andrei Iancu
    1.4. Set enable_double_rr parameter
    1.5. Set add_username parameter
    1.6. enable_socket_mismatch_warning usage
-   1.7. loose_route usage
-   1.8. record_route usage
-   1.9. record_route_preset usage
-   1.10. record_route_advertised_address usage
-   1.11. add_rr_param usage
-   1.12. check_route_param usage
-   1.13. is_direction usage
-   1.14. $route_uri
+   1.7. custom_user_avp usage
+   1.8. loose_route usage
+   1.9. record_route usage
+   1.10. record_route_preset usage
+   1.11. record_route_advertised_address usage
+   1.12. add_rr_param usage
+   1.13. check_route_param usage
+   1.14. is_direction usage
+   1.15. $route_uri
    2.1. record_route usage
    2.2. record_route_advertised_address usage
    2.3. Loading RR module's API from another module
 
 Chapter 1. Admin Guide
 
-   Table of Contents
-
-   1. Overview
-   2. Dialog support
-   3. Dependencies
-
-        3.1. Kamailio Modules
-        3.2. External Libraries or Applications
-
-   4. Parameters
-
-        4.1. enable_full_lr (integer)
-        4.2. append_fromtag (integer)
-        4.3. enable_double_rr (integer)
-        4.4. add_username (integer)
-        4.5. enable_socket_mismatch_warning (integer)
-
-   5. Functions
-
-        5.1. loose_route()
-        5.2. record_route() and record_route(string)
-        5.3. record_route_preset(string [,string2])
-        5.4. record_route_advertised_address(address)
-        5.5. add_rr_param(param)
-        5.6. check_route_param(re)
-        5.7. is_direction(dir)
-
-   6. Exported Pseudo Variables
-
-        6.1. $route_uri
-
-1. Overview
+1.1. Overview
 
    The module contains record routing logic
 
-2. Dialog support
+1.2. Dialog support
 
    Kamailio is basically only a transaction statefull proxy, without any
    dialog support build in. There are many features/services which
@@ -159,8 +130,8 @@ Chapter 1. Admin Guide
    3261 (see 12.1.1 UAS behavior).
 
    For this purpose, the modules offers the following functions:
-     * add_rr_param() - see Section 5.5, “ add_rr_param(param) ”
-     * check_route_param() - see Section 5.6, “ check_route_param(re) ”
+     * add_rr_param() - see Section 1.5.5, “add_rr_param(param)”
+     * check_route_param() - see Section 1.5.6, “check_route_param(re)”
 
    Example 1.1. Dialog support in RR module
 UAC                       Kamailio PROXY                          UAS
@@ -177,32 +148,23 @@ UAC                       Kamailio PROXY                          UAS
 <------ BYE -------        loose_route()          <----- BYE -------
                     check_route_param(";foo=true")
 
-3. Dependencies
-
-   3.1. Kamailio Modules
-   3.2. External Libraries or Applications
+1.3. Dependencies
 
-3.1. Kamailio Modules
+1.3.1. Kamailio Modules
 
    The following modules must be loaded before this module:
      * (optional) The "outbound" module is needed for outbound routing as
        per RFC 5626.
 
-3.2. External Libraries or Applications
+1.3.2. External Libraries or Applications
 
    The following libraries or applications must be installed before
    running Kamailio with this module loaded:
      * None.
 
-4. Parameters
+1.4. Parameters
 
-   4.1. enable_full_lr (integer)
-   4.2. append_fromtag (integer)
-   4.3. enable_double_rr (integer)
-   4.4. add_username (integer)
-   4.5. enable_socket_mismatch_warning (integer)
-
-4.1. enable_full_lr (integer)
+1.4.1. enable_full_lr (integer)
 
    If set to 1 then “;lr=on” instead of just “;lr” will be used. This is
    to overcome problems with broken UAs which strip “;lr” parameter when
@@ -216,7 +178,7 @@ UAC                       Kamailio PROXY                          UAS
 modparam("rr", "enable_full_lr", 1)
 ...
 
-4.2. append_fromtag (integer)
+1.4.2. append_fromtag (integer)
 
    If turned on, request's from-tag is appended to record-route; that's
    useful for understanding whether subsequent requests (such as BYE) come
@@ -230,7 +192,7 @@ modparam("rr", "enable_full_lr", 1)
 modparam("rr", "append_fromtag", 0)
 ...
 
-4.3. enable_double_rr (integer)
+1.4.3. enable_double_rr (integer)
 
    There are some situations when the server needs to insert two
    Record-Route header fields instead of one. For example when using two
@@ -248,7 +210,7 @@ modparam("rr", "append_fromtag", 0)
 modparam("rr", "enable_double_rr", 0)
 ...
 
-4.4. add_username (integer)
+1.4.4. add_username (integer)
 
    If set to a non 0 value (which means yes), the username part will be
    also added in the Record-Route URI.
@@ -264,7 +226,7 @@ modparam("rr", "enable_double_rr", 0)
 modparam("rr", "add_username", 1)
 ...
 
-4.5. enable_socket_mismatch_warning (integer)
+1.4.5. enable_socket_mismatch_warning (integer)
 
    When a preset record-route header is forced in Kamailio config and the
    host from the record-route header is not the same as the host server, a
@@ -280,17 +242,29 @@ modparam("rr", "add_username", 1)
 modparam("rr", "enable_socket_mismatch_warning", 0)
 ...
 
-5. Functions
+1.4.6. custom_user_avp (avp string)
+
+   When enable_username is enabled, a call to record_route will add the
+   username of the RequestURI to the Record-Route URI. This parameter
+   allows you to setup an AVP with which you can customise the username to
+   be added in the Record-Route URI.
 
-   5.1. loose_route()
-   5.2. record_route() and record_route(string)
-   5.3. record_route_preset(string [,string2])
-   5.4. record_route_advertised_address(address)
-   5.5. add_rr_param(param)
-   5.6. check_route_param(re)
-   5.7. is_direction(dir)
+   Default value: if not set, the std add_username behaviour is used -
+   i.e. Request URI username.
 
-5.1.  loose_route()
+   Example 1.7. custom_user_avp usage
+...
+modparam("rr", "custom_user_avp", "$avp(RR_CUSTOMER_USER_AVP)")
+
+#usage in cfg file
+$avp(RR_CUSTOM_USER_AVP)="mo";
+record_route();
+
+...
+
+1.5. Functions
+
+1.5.1. loose_route()
 
    The function performs routing of SIP requests which contain a route
    set. The name is a little bit confusing, as this function also routes
@@ -328,12 +302,12 @@ modparam("rr", "enable_socket_mismatch_warning", 0)
 
    This function can be used from REQUEST_ROUTE.
 
-   Example 1.7. loose_route usage
+   Example 1.8. loose_route usage
 ...
 loose_route();
 ...
 
-5.2.  record_route() and record_route(string)
+1.5.2. record_route() and record_route(string)
 
    The function adds a new Record-Route header field. The header field
    will be inserted in the message before any other Record-Route header
@@ -351,12 +325,12 @@ loose_route();
    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
    FAILURE_ROUTE.
 
-   Example 1.8. record_route usage
+   Example 1.9. record_route usage
 ...
 record_route();
 ...
 
-5.3.  record_route_preset(string [,string2])
+1.5.3. record_route_preset(string [,string2])
 
    This function will put the string into Record-Route, don't use unless
    you know what you are doing.
@@ -379,12 +353,12 @@ record_route();
    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
    FAILURE_ROUTE.
 
-   Example 1.9. record_route_preset usage
+   Example 1.10. record_route_preset usage
 ...
 record_route_preset("1.2.3.4:5090");
 ...
 
-5.4.  record_route_advertised_address(address)
+1.5.4. record_route_advertised_address(address)
 
    The function adds a new Record-Route header field using the address
    given. The header field will be inserted in the message before any
@@ -406,18 +380,18 @@ record_route_preset("1.2.3.4:5090");
    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
    FAILURE_ROUTE.
 
-   Example 1.10. record_route_advertised_address usage
+   Example 1.11. record_route_advertised_address usage
 ...
 record_route_advertised_address("1.2.3.4:5080");
 ...
 
-5.5.  add_rr_param(param)
+1.5.5. add_rr_param(param)
 
    Adds a parameter to the Record-Route URI (param must be in
    “;name=value” format. The function may be called also before or after
    the record_route() or record_route_advertised_address() calls (see
-   Section 5.2, “ record_route() and record_route(string) ” or
-   Section 5.4, “ record_route_advertised_address(address) ”)).
+   Section 1.5.2, “record_route() and record_route(string)” or
+   Section 1.5.4, “record_route_advertised_address(address)”)).
 
    Meaning of the parameters is as follows:
      * param - String containing the URI parameter to be added. It must
@@ -426,37 +400,37 @@ record_route_advertised_address("1.2.3.4:5080");
    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
    FAILURE_ROUTE.
 
-   Example 1.11. add_rr_param usage
+   Example 1.12. add_rr_param usage
 ...
 add_rr_param(";nat=yes");
 ...
 
-5.6.  check_route_param(re)
+1.5.6. check_route_param(re)
 
    The function checks if the URI parameters of the local Route header
    (corresponding to the local server) matches the given regular
-   expression. It must be call after loose_route() (see Section 5.1, “
-   loose_route() ”).
+   expression. It must be call after loose_route() (see Section 1.5.1,
+   “loose_route()”).
 
    Meaning of the parameters is as follows:
      * re - regular expression to check against the Route URI parameters.
 
    This function can be used from REQUEST_ROUTE.
 
-   Example 1.12. check_route_param usage
+   Example 1.13. check_route_param usage
 ...
 if (check_route_param("nat=yes")) {
     setflag(6);
 }
 ...
 
-5.7.  is_direction(dir)
+1.5.7. is_direction(dir)
 
    The function checks the flow direction of in-dialog requests. This
    function uses the “ftag” prameter from the Route header, therefore the
-   append_fromtag (see Section 4.2, “append_fromtag (integer)” module
+   append_fromtag (see Section 1.4.2, “append_fromtag (integer)” module
    parameter must be enabled. Also this must be called only after
-   loose_route() (see Section 5.1, “ loose_route() ”).
+   loose_route() (see Section 1.5.1, “loose_route()”).
 
    The function returns true if the “dir” is the same with the request's
    flow direction.
@@ -471,7 +445,7 @@ if (check_route_param("nat=yes")) {
 
    This function can be used from REQUEST_ROUTE.
 
-   Example 1.13. is_direction usage
+   Example 1.14. is_direction usage
 ...
 if (is_direction("downstream")) {
     xdbg("in-dialog request from caller to callee (downstream) ($rm)\n");
@@ -480,39 +454,23 @@ if (is_direction("downstream")) {
 }
 ...
 
-6. Exported Pseudo Variables
-
-   6.1. $route_uri
+1.6. Exported Pseudo Variables
 
-6.1. $route_uri
+1.6.1. $route_uri
 
    Returns the URI of the top route-header.
 
-   Example 1.14. $route_uri
+   Example 1.15. $route_uri
 ...
     xdbg("Route-URI is: $route_uri\n");
 ...
 
 Chapter 2. Developer Guide
 
-   Table of Contents
-
-   1. Available Functions
-
-        1.1. record_route(string)
-        1.2. record_route_advertised_address(string)
-        1.3. add_rr_param( msg, param)
-        1.4. check_route_param( msg, re)
-        1.5. is_direction( msg, dir)
-        1.6. get_route_param( msg, name, val)
-        1.7. register_rrcb( callback, param)
-
-   2. Examples
-
    The RR module provides an internal API to be used by other Kamailio
    modules. The API offers support for SIP dialog based functionalities -
-   for more about the dialog support offered by RR module, see Section 2,
-   “Dialog support”.
+   for more about the dialog support offered by RR module, see
+   Section 1.2, “Dialog support”.
 
    For internal(non-script) usage, the RR module offers to other module
    the possibility to register callback functions to be executed each time
@@ -520,17 +478,9 @@ Chapter 2. Developer Guide
    as parameter the register parameter and the Route header parameter
    string.
 
-1. Available Functions
-
-   1.1. record_route(string)
-   1.2. record_route_advertised_address(string)
-   1.3. add_rr_param( msg, param)
-   1.4. check_route_param( msg, re)
-   1.5. is_direction( msg, dir)
-   1.6. get_route_param( msg, name, val)
-   1.7. register_rrcb( callback, param)
+2.1. Available Functions
 
-1.1.  record_route(string)
+2.1.1.  record_route(string)
 
    The function adds a new Record-Route header field. The header field
    will be inserted in the message before any other Record-Route header
@@ -548,7 +498,7 @@ Chapter 2. Developer Guide
 record_route();
 ...
 
-1.2.  record_route_advertised_address(string)
+2.1.2.  record_route_advertised_address(string)
 
    This function will add the string into a new Record-Route header field.
    Don't use unless you know what you are doing. The header field will be
@@ -566,7 +516,7 @@ record_route();
 record_route_advertised_address("1.2.3.4:5090");
 ...
 
-1.3.  add_rr_param( msg, param)
+2.1.3.  add_rr_param( msg, param)
 
    Adds a parameter to the requests's Record-Route URI (param must be in
    “;name=value” format).
@@ -579,7 +529,7 @@ record_route_advertised_address("1.2.3.4:5090");
      * str* param - parameter to be added to the Record-Route header - it
        must be in “;name=value” format.
 
-1.4.  check_route_param( msg, re)
+2.1.4.  check_route_param( msg, re)
 
    The function checks for the request “msg” if the URI parameters of the
    local Route header (corresponding to the local server) matches the
@@ -594,11 +544,11 @@ record_route_advertised_address("1.2.3.4:5090");
      * regex_t* param - compiled regular expression to be checked against
        the Route header parameters.
 
-1.5.  is_direction( msg, dir)
+2.1.5.  is_direction( msg, dir)
 
    The function checks the flow direction of the request “msg”. As for
    checking it's used the “ftag” Route header parameter, the
-   append_fromtag (see Section 4.2, “append_fromtag (integer)” module
+   append_fromtag (see Section 1.4.2, “append_fromtag (integer)” module
    parameter must be enables. Also this must be call only after the
    loose_route is done.
 
@@ -610,7 +560,7 @@ record_route_advertised_address("1.2.3.4:5090");
      * int dir - direction to be checked against. It may be
        “RR_FLOW_UPSTREAM” or “RR_FLOW_DOWNSTREAM”.
 
-1.6.  get_route_param( msg, name, val)
+2.1.6.  get_route_param( msg, name, val)
 
    The function search in to the “msg”'s Route header parameters the
    parameter called “name” and returns its value into “val”. It must be
@@ -626,7 +576,7 @@ record_route_advertised_address("1.2.3.4:5090");
      * str *val - returns the value of the searched Route header parameter
        if found. It might be empty string if the parameter had no value.
 
-1.7.  register_rrcb( callback, param)
+2.1.7.  register_rrcb( callback, param)
 
    The function register a new callback (along with its parameter). The
    callback will be called when a loose route will be performed for the
@@ -638,7 +588,7 @@ record_route_advertised_address("1.2.3.4:5090");
      * rr_cb_t callback - callback function to be registered.
      * void *param - parameter to be passed to the callback function.
 
-2. Examples
+2.2. Examples
 
    Example 2.3. Loading RR module's API from another module
 ...