rr: documentation for remove_record_route()

modules/rr/README

@@ -20,11 +20,11 @@ Edited by
 
 Bogdan-Andrei Iancu
 
-   Copyright (c) 2003 FhG FOKUS
+   Copyright © 2003 FhG FOKUS
 
-   Copyright (c) 2005 Voice Sistem SRL
+   Copyright © 2005 Voice Sistem SRL
 
-   Copyright (c) 2011 Carsten Bock, [email protected]
+   Copyright © 2011 Carsten Bock, [email protected]
      __________________________________________________________________
 
    Table of Contents
@@ -51,11 +51,12 @@ Bogdan-Andrei Iancu
 
               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.3. remove_record_route()
+              5.4. record_route_preset(string [,string2])
+              5.5. record_route_advertised_address(address)
+              5.6. add_rr_param(param)
+              5.7. check_route_param(re)
+              5.8. is_direction(dir)
 
         6. Exported Pseudo Variables
 
@@ -86,12 +87,13 @@ Bogdan-Andrei Iancu
    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
+   1.10. remove_record_route usage
+   1.11. record_route_preset usage
+   1.12. record_route_advertised_address usage
+   1.13. add_rr_param usage
+   1.14. check_route_param usage
+   1.15. is_direction usage
+   1.16. $route_uri
    2.1. record_route usage
    2.2. record_route_advertised_address usage
    2.3. Loading RR module's API from another module
@@ -120,11 +122,12 @@ Chapter 1. Admin Guide
 
         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.3. remove_record_route()
+        5.4. record_route_preset(string [,string2])
+        5.5. record_route_advertised_address(address)
+        5.6. add_rr_param(param)
+        5.7. check_route_param(re)
+        5.8. is_direction(dir)
 
    6. Exported Pseudo Variables
 
@@ -162,8 +165,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 5.6, "add_rr_param(param)"
+     * check_route_param() - see Section 5.7, "check_route_param(re)"
 
    Example 1.1. Dialog support in RR module
 UAC                       Kamailio PROXY                          UAS
@@ -308,11 +311,12 @@ record_route();
 
    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.3. remove_record_route()
+   5.4. record_route_preset(string [,string2])
+   5.5. record_route_advertised_address(address)
+   5.6. add_rr_param(param)
+   5.7. check_route_param(re)
+   5.8. is_direction(dir)
 
 5.1. loose_route()
 
@@ -383,7 +387,21 @@ loose_route();
 record_route();
 ...
 
-5.3. record_route_preset(string [,string2])
+5.3. remove_record_route()
+
+   The function removes the internal lumps added by record_route()
+   functions.
+
+   Can be used to revert adding Record-Route header(s).
+
+   This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
+
+   Example 1.10. remove_record_route usage
+...
+remove_record_route();
+...
+
+5.4. record_route_preset(string [,string2])
 
    This function will put the string into Record-Route, don't use unless
    you know what you are doing.
@@ -406,12 +424,12 @@ record_route();
    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
    FAILURE_ROUTE.
 
-   Example 1.10. record_route_preset usage
+   Example 1.11. record_route_preset usage
 ...
 record_route_preset("1.2.3.4:5090");
 ...
 
-5.4. record_route_advertised_address(address)
+5.5. 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
@@ -433,17 +451,17 @@ record_route_preset("1.2.3.4:5090");
    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
    FAILURE_ROUTE.
 
-   Example 1.11. record_route_advertised_address usage
+   Example 1.12. record_route_advertised_address usage
 ...
 record_route_advertised_address("1.2.3.4:5080");
 ...
 
-5.5. add_rr_param(param)
+5.6. 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,
+   Section 5.2, "record_route() and record_route(string)" or Section 5.5,
    "record_route_advertised_address(address)")).
 
    Meaning of the parameters is as follows:
@@ -453,12 +471,12 @@ record_route_advertised_address("1.2.3.4:5080");
    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
    FAILURE_ROUTE.
 
-   Example 1.12. add_rr_param usage
+   Example 1.13. add_rr_param usage
 ...
 add_rr_param(";nat=yes");
 ...
 
-5.6. check_route_param(re)
+5.7. 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
@@ -470,14 +488,14 @@ add_rr_param(";nat=yes");
 
    This function can be used from REQUEST_ROUTE.
 
-   Example 1.13. check_route_param usage
+   Example 1.14. check_route_param usage
 ...
 if (check_route_param("nat=yes")) {
     setflag(6);
 }
 ...
 
-5.7. is_direction(dir)
+5.8. 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
@@ -498,7 +516,7 @@ if (check_route_param("nat=yes")) {
 
    This function can be used from REQUEST_ROUTE.
 
-   Example 1.14. is_direction usage
+   Example 1.15. is_direction usage
 ...
 if (is_direction("downstream")) {
     xdbg("in-dialog request from caller to callee (downstream) ($rm)\n");
@@ -515,7 +533,7 @@ if (is_direction("downstream")) {
 
    Returns the URI of the top route-header.
 
-   Example 1.15. $route_uri
+   Example 1.16. $route_uri
 ...
     xdbg("Route-URI is: $route_uri\n");
 ...
@@ -557,7 +575,7 @@ Chapter 2. Developer Guide
    1.6. get_route_param( msg, name, val)
    1.7. register_rrcb( callback, param)
 
-1.1.  record_route(string)
+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
@@ -575,7 +593,7 @@ Chapter 2. Developer Guide
 record_route();
 ...
 
-1.2.  record_route_advertised_address(string)
+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
@@ -593,7 +611,7 @@ record_route();
 record_route_advertised_address("1.2.3.4:5090");
 ...
 
-1.3.  add_rr_param( msg, param)
+1.3. add_rr_param( msg, param)
 
    Adds a parameter to the requests's Record-Route URI (param must be in
    ";name=value" format).
@@ -606,7 +624,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)
+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
@@ -621,7 +639,7 @@ 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)
+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
@@ -637,7 +655,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)
+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
@@ -653,7 +671,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)
+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

modules/rr/doc/rr_admin.xml

@@ -360,6 +360,31 @@ record_route();
       </example>
     </section>
 
+    <section id="remove-record-route-id">
+		<title><function moreinfo="none">remove_record_route()</function></title>
+
+		<para>The function removes the internal lumps added by
+			record_route() functions.
+		</para>
+
+		<para>
+			Can be used to revert adding Record-Route header(s).
+		</para>
+		<para>
+			This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
+		</para>
+
+      <example>
+        <title><function>remove_record_route</function> usage</title>
+
+        <programlisting format="linespecific">
+...
+remove_record_route();
+...
+</programlisting>
+      </example>
+    </section>
+
     <section>
       <title><function moreinfo="none">record_route_preset(string
       [,string2])</function></title>