modules_k/rr: Exported record_route_advertised_address function to config file

- Exported the C API function to the config file
- CHange by Hugh Waite @ Crocodile RCS

modules_k/rr/README

@@ -1,3 +1,4 @@
+
 rr Module
 
 Jan Janak
@@ -20,12 +21,12 @@ Edited by
 
 Bogdan-Andrei Iancu
 
-   Copyright © 2003 FhG FOKUS
+   Copyright © 2003 FhG FOKUS
 
-   Copyright © 2005 Voice Sistem SRL
+   Copyright © 2005 Voice Sistem SRL
 
-   Copyright © 2011 Carsten Bock, [email protected]
-     __________________________________________________________________
+   Copyright © 2011 Carsten Bock, [email protected]
+     _________________________________________________________________
 
    Table of Contents
 
@@ -48,12 +49,13 @@ Bogdan-Andrei Iancu
 
         5. Functions
 
-              5.1. loose_route()
-              5.2. record_route() and record_route(string)
-              5.3. record_route_preset(string [,string2])
-              5.4. add_rr_param(param)
-              5.5. check_route_param(re)
-              5.6. is_direction(dir)
+              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
 
@@ -63,13 +65,13 @@ Bogdan-Andrei Iancu
 
         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)
+              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
 
@@ -84,10 +86,11 @@ Bogdan-Andrei Iancu
    1.7. loose_route usage
    1.8. record_route usage
    1.9. record_route_preset usage
-   1.10. add_rr_param usage
-   1.11. check_route_param usage
-   1.12. is_direction usage
-   1.13. $route_uri
+   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
    2.1. record_route usage
    2.2. record_route_advertised_address usage
    2.3. Loading RR module's API from another module
@@ -113,12 +116,13 @@ Chapter 1. Admin Guide
 
    5. Functions
 
-        5.1. loose_route()
-        5.2. record_route() and record_route(string)
-        5.3. record_route_preset(string [,string2])
-        5.4. add_rr_param(param)
-        5.5. check_route_param(re)
-        5.6. is_direction(dir)
+        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
 
@@ -130,34 +134,34 @@ Chapter 1. Admin Guide
 
 2. Dialog support
 
-   Kamailio is basically only a transaction statefull proxy, without any
-   dialog support build in. There are many features/services which
-   actually requires a dialog awareness, like storing the information in
-   the dialog creation stage, information which will be used during the
+   Kamailio  is basically only a transaction statefull proxy, without any
+   dialog  support  build  in.  There  are  many  features/services which
+   actually  requires a dialog awareness, like storing the information in
+   the  dialog  creation stage, information which will be used during the
    whole dialog existence.
 
-   The most urging example is NAT traversal, in dealing with the within
-   the dialog INVITEs (re-INVITEs). When processing the initial INVITE,
+   The  most  urging example is NAT traversal, in dealing with the within
+   the  dialog  INVITEs (re-INVITEs). When processing the initial INVITE,
    the proxy detects if the caller or callee is behind some NAT and fixes
    the signalling and media parts - since not all the detection mechanism
    are available for within the dialog requests (like usrloc), to be able
-   to fix correspondingly the sequential requests, the proxy must remember
-   that the original request was NAT processed. There are many other cases
-   where dialog awareness fixes or helps.
+   to  fix  correspondingly  the  sequential  requests,  the  proxy  must
+   remember  that  the original request was NAT processed. There are many
+   other cases where dialog awareness fixes or helps.
 
-   The solution is to store additional dialog-related information in the
+   The  solution is to store additional dialog-related information in the
    routing set (Record-Route/Route headers), headers which show up in all
-   sequential requests. So any information added to the Record-Route
-   header will be found (with no direction dependencies) in Route header
+   sequential  requests.  So  any  information  added to the Record-Route
+   header  will be found (with no direction dependencies) in Route header
    (corresponding to the proxy address).
 
-   As storage container, the parameters of the Record-Route / Route header
-   will be used - Record-Route parameters mirroring are reinforced by RFC
-   3261 (see 12.1.1 UAS behavior).
+   As  storage  container,  the  parameters  of  the Record-Route / Route
+   header will be used - Record-Route parameters mirroring are reinforced
+   by RFC 3261 (see 12.1.1 UAS behavior).
 
    For this purpose, the modules offers the following functions:
-     * add_rr_param() - see Section 5.4, “ add_rr_param(param) �
-     * check_route_param() - see Section 5.5, “ check_route_param(re) �
+     * add_rr_param() - see Section 5.5, " add_rr_param(param) "
+     * check_route_param() - see Section 5.6, " check_route_param(re) "
 
    Example 1.1. Dialog support in RR module
 UAC                       Kamailio PROXY                          UAS
@@ -186,7 +190,7 @@ UAC                       Kamailio PROXY                          UAS
 
 3.2. External Libraries or Applications
 
-   The following libraries or applications must be installed before
+   The  following  libraries  or  applications  must  be installed before
    running Kamailio with this module loaded:
      * None.
 
@@ -200,12 +204,12 @@ UAC                       Kamailio PROXY                          UAS
 
 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
-   generating Route header fields from Record-Route (“;lr=on� seems to
+   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
+   generating  Route  header  fields from Record-Route (";lr=on" seems to
    help).
 
-   Default value is 0 (no).
+   Default value is 0 (no). 
 
    Example 1.2. Set enable_full_lr parameter
 ...
@@ -214,12 +218,12 @@ modparam("rr", "enable_full_lr", 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
-   from caller (route's from-tag==BYE's from-tag) or callee (route's
+   If  turned  on, request's from-tag is appended to record-route; that's
+   useful  for  understanding  whether  subsequent requests (such as BYE)
+   come from caller (route's from-tag==BYE's from-tag) or callee (route's
    from-tag==BYE's to-tag)
 
-   Default value is 1 (yes).
+   Default value is 1 (yes). 
 
    Example 1.3. Set append_fromtag parameter
 ...
@@ -228,13 +232,13 @@ modparam("rr", "append_fromtag", 0)
 
 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
-   disconnected networks or doing cross-protocol forwarding from UDP->TCP.
-   This parameter enables inserting of 2 Record-Routes. The server will
-   later remove both of them.
+   There  are  some  situations  when  the  server  needs  to  insert two
+   Record-Route  header fields instead of one. For example when using two
+   disconnected   networks   or   doing  cross-protocol  forwarding  from
+   UDP->TCP.  This  parameter  enables  inserting of 2 Record-Routes. The
+   server will later remove both of them.
 
-   Default value is 1 (yes).
+   Default value is 1 (yes). 
 
    Example 1.4. Set enable_double_rr parameter
 ...
@@ -243,10 +247,10 @@ modparam("rr", "enable_double_rr", 0)
 
 4.4. add_username (integer)
 
-   If set to a non 0 value (which means yes), the username part will be
+   If  set  to a non 0 value (which means yes), the username part will be
    also added in the Record-Route URI.
 
-   Default value is 0 (no).
+   Default value is 0 (no). 
 
    Example 1.5. Set add_username parameter
 ...
@@ -256,13 +260,13 @@ modparam("rr", "add_username", 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
-   warning will be printed out in the logs. The
-   'enable_socket_mismatch_warning' parameter enables or disables the
-   warning. When Kamailio is behind a NATed firewall, we don't want this
+   host  from the record-route header is not the same as the host server,
+   a    warning    will    be    printed    out    in   the   logs.   The
+   'enable_socket_mismatch_warning'  parameter  enables  or  disables the
+   warning.  When Kamailio is behind a NATed firewall, we don't want this
    warning to be printed for every bridged call.
 
-   Default value is 1 (yes).
+   Default value is 1 (yes). 
 
    Example 1.6. enable_socket_mismatch_warning usage
 ...
@@ -271,38 +275,39 @@ modparam("rr", "enable_socket_mismatch_warning", 0)
 
 5. Functions
 
-   5.1. loose_route()
-   5.2. record_route() and record_route(string)
-   5.3. record_route_preset(string [,string2])
-   5.4. add_rr_param(param)
-   5.5. check_route_param(re)
-   5.6. is_direction(dir)
+   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) 
 
 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
-   requests which are in the “strict router� format.
-
-   This function is usually used to route in-dialog requests (like ACK,
-   BYE, reINVITE). Nevertheless also out-of-dialog requests can have a
-   “pre-loaded route set� and my be routed with loose_route. It also takes
-   care of translating between strict-routers and loose-router.
-
-   The loose_route function analyzes the Route: headers in the requests.
-   If there is no Route: header, the function returns FALSE and routing
-   should be done with normal lookup functions. If a Route: header is
-   found, the function returns 1 and behaves as described in section 16.12
-   of RFC 3261. There is only one exception: If the request is
-   out-of-dialog (no to-tag) and there is only one Route: header
-   indicating the local proxy, then the Route: header is removed and the
+   The  function  performs  routing of SIP requests which contain a route
+   set.  The name is a little bit confusing, as this function also routes
+   requests which are in the "strict router" format.
+
+   This  function  is usually used to route in-dialog requests (like ACK,
+   BYE,  reINVITE).  Nevertheless  also out-of-dialog requests can have a
+   "pre-loaded  route  set"  and  my  be routed with loose_route. It also
+   takes care of translating between strict-routers and loose-router.
+
+   The  loose_route function analyzes the Route: headers in the requests.
+   If  there  is no Route: header, the function returns FALSE and routing
+   should  be  done  with  normal lookup functions. If a Route: header is
+   found,  the  function  returns  1  and behaves as described in section
+   16.12  of  RFC  3261.  There  is only one exception: If the request is
+   out-of-dialog  (no  to-tag)  and  there  is  only  one  Route:  header
+   indicating  the local proxy, then the Route: header is removed and the
    function returns FALSE.
 
-   Make sure your loose_routing function can't be used by attackers to
+   Make  sure  your  loose_routing function can't be used by attackers to
    bypass proxy authorization.
 
-   The loose_routing topic is very complex. See the RFC3261 for more
-   details (grep for “route set� is a good starting point in this
+   The  loose_routing  topic  is  very  complex. See the RFC3261 for more
+   details  (grep  for  "route  set"  is  a  good  starting point in this
    comprehensive RFC).
 
    This function can be used from REQUEST_ROUTE.
@@ -314,15 +319,15 @@ loose_route();
 
 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
+   The  function  adds  a new Record-Route header field. The header field
+   will  be  inserted in the message before any other Record-Route header
    fields.
 
-   If any string is passed as parameter, it will be appended as URI
-   parameter to the Record-Route header. The string must follow the
-   “;name=value� scheme and it may contain pseudo-variables.
+   If  any  string  is  passed  as  parameter, it will be appended as URI
+   parameter  to  the  Record-Route  header.  The  string must follow the
+   ";name=value" scheme and it may contain pseudo-variables.
 
-   This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
+   This  function  can  be  used  from  REQUEST_ROUTE,  BRANCH_ROUTE  and
    FAILURE_ROUTE.
 
    Example 1.8. record_route usage
@@ -332,20 +337,20 @@ record_route();
 
 5.3.  record_route_preset(string [,string2])
 
-   This function will put the string into Record-Route, don't use unless
+   This  function will put the string into Record-Route, don't use unless
    you know what you are doing.
 
    Meaning of the parameters is as follows:
      * string - String to be inserted into the first header field; it may
        contain pseudo-variables.
-     * string2 - String to be inserted into the second header field; it
+     * string2  -  String to be inserted into the second header field; it
        may contain pseudo-variables.
 
-   Note: If 'string2' is present, then the 'string' param is pointing to
-   the outbound interface and the 'string2' param is pointing to the
+   Note:  If 'string2' is present, then the 'string' param is pointing to
+   the  outbound  interface  and  the  'string2' param is pointing to the
    inbound interface.
 
-   This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
+   This  function  can  be  used  from  REQUEST_ROUTE,  BRANCH_ROUTE  and
    FAILURE_ROUTE.
 
    Example 1.9. record_route_preset usage
@@ -353,66 +358,89 @@ record_route();
 record_route_preset("1.2.3.4:5090");
 ...
 
-5.4.  add_rr_param(param)
+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
+   other Record-Route header fields.
+
+   Meaning of the parameter is as follows:
+     * address  - Advertised address to use in the header; it may contain
+       pseudo-variables.
 
-   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() call (see Section 5.2, “ record_route() and
-   record_route(string) �).
+   If  double  record-routing is enabled two Record-Route headers will be
+   inserted  with the same given address with different transports if the
+   transport changes.
+
+   This  function  can  be  used  from  REQUEST_ROUTE,  BRANCH_ROUTE  and
+   FAILURE_ROUTE.
+
+   Example 1.10. record_route_advertised_address usage
+...
+record_route_advertised_address("1.2.3.4:5080");
+...
+
+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) ")).
 
    Meaning of the parameters is as follows:
-     * param - String containing the URI parameter to be added. It must
-       follow the “;name=value� scheme; it may contain pseudo-variables.
+     * param  -  String containing the URI parameter to be added. It must
+       follow the ";name=value" scheme; it may contain pseudo-variables.
 
-   This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
+   This  function  can  be  used  from  REQUEST_ROUTE,  BRANCH_ROUTE  and
    FAILURE_ROUTE.
 
-   Example 1.10. add_rr_param usage
+   Example 1.11. add_rr_param usage
 ...
 add_rr_param(";nat=yes");
 ...
 
-5.5.  check_route_param(re)
+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() �).
+   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() ").
 
    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.11. check_route_param usage
+   Example 1.12. check_route_param usage
 ...
 if (check_route_param("nat=yes")) {
     setflag(6);
 }
 ...
 
-5.6.  is_direction(dir)
+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
-   parameter must be enabled. Also this must be called only after
-   loose_route() (see Section 5.1, “ loose_route() �).
+   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
+   parameter  must  be  enabled.  Also  this  must  be  called only after
+   loose_route() (see Section 5.1, " loose_route() ").
 
-   The function returns true if the “dir� is the same with the request's
+   The  function returns true if the "dir" is the same with the request's
    flow direction.
 
-   The “downstream� direction means that the request is in the same
+   The  "downstream"  direction  means  that  the  request is in the same
    direction as the initial request that created the dialog.
 
    Meaning of the parameters is as follows:
-     * dir - string containing the direction to be checked. It may be
-       “upstream� (from callee to caller) or “downstream� (caller to
+     * dir  -  string  containing  the direction to be checked. It may be
+       "upstream"  (from  callee  to  caller)  or "downstream" (caller to
        callee).
 
    This function can be used from REQUEST_ROUTE.
 
-   Example 1.12. is_direction usage
+   Example 1.13. is_direction usage
 ...
 if (is_direction("downstream")) {
     xdbg("in-dialog request from caller to callee (downstream) ($rm)\n");
@@ -429,7 +457,7 @@ if (is_direction("downstream")) {
 
    Returns the URI of the top route-header.
 
-   Example 1.13. $route_uri
+   Example 1.14. $route_uri
 ...
     xdbg("Route-URI is: $route_uri\n");
 ...
@@ -440,48 +468,48 @@ Chapter 2. Developer Guide
 
    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)
+        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
+   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�.
+   "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
-   a local Route header is processed. The callback function will receive
-   as parameter the register parameter and the Route header parameter
-   string.
+   For  internal(non-script)  usage, the RR module offers to other module
+   the  possibility  to  register  callback functions to be executed each
+   time  a  local  Route  header is processed. The callback function will
+   receive  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)
+   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) 
 
 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
+   The  function  adds  a new Record-Route header field. The header field
+   will  be  inserted in the message before any other Record-Route header
    fields.
 
-   If any string is passed as parameter, it will be appended as URI
-   parameter to the Record-Route header. The string must follow the
-   “;name=value� scheme and it may contain pseudo-variables.
+   If  any  string  is  passed  as  parameter, it will be appended as URI
+   parameter  to  the  Record-Route  header.  The  string must follow the
+   ";name=value" scheme and it may contain pseudo-variables.
 
-   This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
+   This  function  can  be  used  from  REQUEST_ROUTE,  BRANCH_ROUTE  and
    FAILURE_ROUTE.
 
    Example 2.1. record_route usage
@@ -491,16 +519,17 @@ record_route();
 
 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
-   inserted in the message before any other Record-Route header fields.
+   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  inserted in the message before any other Record-Route header
+   fields.
 
    Meaning of the parameters is as follows:
      * string - String to be inserted into the header field.
 
-   Calls to add_rr_param() will add parameters to the Record-Route header.
-   Note: A second Record-Route will be inserted if the transport used on
-   the inbound and outbound interfaces changes.
+   Calls  to  add_rr_param()  will  add  parameters  to  the Record-Route
+   header.  Note: A second Record-Route will be inserted if the transport
+   used on the inbound and outbound interfaces changes.
 
    Example 2.2. record_route_advertised_address usage
 ...
@@ -509,68 +538,70 @@ record_route_advertised_address("1.2.3.4:5090");
 
 1.3.  add_rr_param( msg, param)
 
-   Adds a parameter to the requests's Record-Route URI (param must be in
-   “;name=value� format).
+   Adds  a parameter to the requests's Record-Route URI (param must be in
+   ";name=value" format).
 
    The function returns 0 on success. Otherwise, -1 is returned.
 
    Meaning of the parameters is as follows:
-     * struct sip_msg* msg - request that will has the parameter “param�
+     * struct  sip_msg* msg - request that will has the parameter "param"
        added to its Record-Route header.
      * str* param - parameter to be added to the Record-Route header - it
-       must be in “;name=value� format.
+       must be in ";name=value" format.
 
 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
-   given regular expression “re�. It must be call after the loose_route
+   The function checks for the request "msg" if the URI parameters of the
+   local  Route  header  (corresponding  to the local server) matches the
+   given  regular  expression "re". It must be call after the loose_route
    was done.
 
    The function returns 0 on success. Otherwise, -1 is returned.
 
    Meaning of the parameters is as follows:
-     * struct sip_msg* msg - request that will has the Route header
+     * struct  sip_msg*  msg  -  request  that  will has the Route header
        parameters checked.
      * regex_t* param - compiled regular expression to be checked against
        the Route header parameters.
 
 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
-   parameter must be enables. Also this must be call only after the
+   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
+   parameter  must  be  enables.  Also  this  must be call only after the
    loose_route is done.
 
-   The function returns 0 if the “dir� is the same with the request's flow
-   direction. Otherwise, -1 is returned.
+   The  function  returns  0  if the "dir" is the same with the request's
+   flow direction. Otherwise, -1 is returned.
 
    Meaning of the parameters is as follows:
-     * struct sip_msg* msg - request that will have the direction checked.
-     * int dir - direction to be checked against. It may be
-       “RR_FLOW_UPSTREAM� or “RR_FLOW_DOWNSTREAM�.
+     * struct  sip_msg*  msg  -  request  that  will  have  the direction
+       checked.
+     * 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)
 
-   The function search in to the “msg�'s Route header parameters the
-   parameter called “name� and returns its value into “val�. It must be
+   The  function  search  in  to  the "msg"'s Route header parameters the
+   parameter  called  "name" and returns its value into "val". It must be
    call only after the loose_route is done.
 
-   The function returns 0 if parameter was found (even if it has no
+   The  function  returns  0  if  parameter  was found (even if it has no
    value). Otherwise, -1 is returned.
 
    Meaning of the parameters is as follows:
-     * struct sip_msg* msg - request that will have the Route header
+     * struct  sip_msg*  msg  -  request  that will have the Route header
        parameter searched.
      * str *name - contains the Route header parameter to be serached.
-     * str *val - returns the value of the searched Route header parameter
-       if found. It might be empty string if the parameter had no value.
+     * 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)
 
-   The function register a new callback (along with its parameter). The
-   callback will be called when a loose route will be performed for the
+   The  function  register a new callback (along with its parameter). The
+   callback  will  be called when a loose route will be performed for the
    local address.
 
    The function returns 0 on success. Otherwise, -1 is returned.

modules_k/rr/doc/rr_admin.xml

@@ -360,6 +360,42 @@ record_route_preset("1.2.3.4:5090");
 		</example>
 	</section>
 
+	<section id="record-route-adv-addr-id">
+		<title>
+		<function moreinfo="none">record_route_advertised_address(address)</function>
+		</title>
+		<para>
+		The function adds a new Record-Route header field using the address given. The
+		header field will be inserted in the message before any other Record-Route header
+		fields.
+		</para>
+		<para>Meaning of the parameter is as follows:</para>
+		<itemizedlist>
+		<listitem>
+			<para>
+			<emphasis>address</emphasis> - Advertised address to use in the header;
+				it may contain pseudo-variables.
+			</para>
+		</listitem>
+		</itemizedlist>
+		<para>
+		If double record-routing is enabled two Record-Route headers will be inserted
+		with the same given address with different transports if the transport changes.
+		</para>
+		<para>
+		This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and 
+		FAILURE_ROUTE.
+		</para>
+		<example>
+		<title><function>record_route_advertised_address</function> usage</title>
+		<programlisting format="linespecific">
+...
+record_route_advertised_address("1.2.3.4:5080");
+...
+</programlisting>
+		</example>
+	</section>
+
 	<section id="add-rr-param-id">
 		<title>
 		<function moreinfo="none">add_rr_param(param)</function>
@@ -367,8 +403,8 @@ record_route_preset("1.2.3.4:5090");
 		<para>
 		Adds a parameter to the Record-Route URI (param must be in 
 		<quote>;name=value</quote> format. The function may be called also 
-		before or after the record_route() call 
-		(see <xref linkend="record-route-id"/>).
+		before or after the record_route() or record_route_advertised_address() calls
+		(see <xref linkend="record-route-id"/> or <xref linkend="record-route-adv-addr-id"/>)).
 		</para>
 		<para>Meaning of the parameters is as follows:</para>
 		<itemizedlist>

modules_k/rr/rr_mod.c

@@ -70,6 +70,7 @@ static int it_list_fixup(void** param, int param_no);
 static int w_loose_route(struct sip_msg *, char *, char *);
 static int w_record_route(struct sip_msg *, char *, char *);
 static int w_record_route_preset(struct sip_msg *,char *, char *);
+static int w_record_route_advertised_address(struct sip_msg *, char *, char *);
 static int w_add_rr_param(struct sip_msg *,char *, char *);
 static int w_check_route_param(struct sip_msg *,char *, char *);
 static int w_is_direction(struct sip_msg *,char *, char *);
@@ -89,6 +90,8 @@ static cmd_export_t cmds[] = {
 			REQUEST_ROUTE|BRANCH_ROUTE|FAILURE_ROUTE},
 	{"record_route_preset",  (cmd_function)w_record_route_preset, 2, it_list_fixup, 0,
 			REQUEST_ROUTE|BRANCH_ROUTE|FAILURE_ROUTE},
+	{"record_route_advertised_address",  (cmd_function)w_record_route_advertised_address, 1, it_list_fixup, 0,
+			REQUEST_ROUTE|BRANCH_ROUTE|FAILURE_ROUTE},
 	{"add_rr_param",         (cmd_function)w_add_rr_param,	1, it_list_fixup, 0,
 			REQUEST_ROUTE|BRANCH_ROUTE|FAILURE_ROUTE},
 	{"check_route_param",    (cmd_function)w_check_route_param, 1, fixup_regexp_null, fixup_free_regexp_null,
@@ -281,6 +284,30 @@ done:
 }
 
 
+/**
+ * wrapper for record_route(msg, params)
+ */
+static int w_record_route_advertised_address(struct sip_msg *msg, char *addr, char *bar)
+{
+	str s;
+
+	if (msg->id == last_rr_msg) {
+		LM_ERR("Double attempt to record-route\n");
+		return -1;
+	}
+
+	if (pv_printf_s(msg, (pv_elem_t*)addr, &s) < 0) {
+		LM_ERR("failed to print the format\n");
+		return -1;
+	}
+	if ( record_route_advertised_address( msg, &s ) < 0)
+		return -1;
+
+	last_rr_msg = msg->id;
+	return 1;
+}
+
+
 static int w_add_rr_param(struct sip_msg *msg, char *key, char *foo)
 {
 	str s;