git:master: improve documentation of is_direction() function - sr-dev

8 Sep 2010

Module: sip-router
Branch: master
Commit: a4bdf3c9c951e052b2db1d3967999f662b7438a5
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=a4bdf3c9...
Author: Klaus Darilion klaus.mailinglists@pernau.at
Committer: Klaus Darilion klaus.mailinglists@pernau.at
Date:   Wed Sep  8 14:57:48 2010 +0200
improve documentation of is_direction() function
---
modules_k/rr/README           |   45 +++++++++++++++++++++-------------------
 modules_k/rr/doc/rr_admin.xml |   20 ++++++++++--------
 2 files changed, 35 insertions(+), 30 deletions(-)

diff --git a/modules_k/rr/README b/modules_k/rr/README
index d4a7038..11ee6a9 100644
--- a/modules_k/rr/README
+++ b/modules_k/rr/README
@@ -241,7 +241,7 @@ modparam("rr", "add_username", 1)
    5.5. check_route_param(re)
    5.6. is_direction(dir)
-5.1. loose_route()
+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
@@ -275,7 +275,7 @@ modparam("rr", "add_username", 1)
 loose_route();
 ...
-5.2. record_route() and record_route(string)
+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
@@ -293,7 +293,7 @@ loose_route();
 record_route();
 ...
-5.3. record_route_preset(string)
+5.3.  record_route_preset(string)
This function will put the string into Record-Route, don't use unless
    you know what you are doing.
@@ -310,7 +310,7 @@ record_route();
 record_route_preset("1.2.3.4:5090");
 ...
-5.4. add_rr_param(param)
+5.4.  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
@@ -329,7 +329,7 @@ record_route_preset("1.2.3.4:5090");
 add_rr_param(";nat=yes");
 ...
-5.5. check_route_param(re)
+5.5.  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
@@ -348,30 +348,33 @@ if (check_route_param("nat=yes")) {
 }
 ...
-5.6. is_direction(dir)
+5.6.  is_direction(dir)
-   The function checks the flow direction of the request. 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
-   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
    flow direction.
-   The "downstream" (UAC to UAS) direction is relative to the initial
-   request that created the dialog.
+   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 UAS to UAC) or "downstream" (UAC to UAS).
+       "upstream" (from callee to caller) or "downstream" (caller to
+       callee).
This function can be used from REQUEST_ROUTE.
Example 1.11. is_direction usage
 ...
-if (is_direction("upstream")) {
-    xdbg("upstream request ($rm)\n");
+if (is_direction("downstream")) {
+    xdbg("in-dialog request from caller to callee (downstream) ($rm)\n");
+} else {
+    xdbg("in-dialog request from callee to caller (upstream) ($rm)\n");
 }
 ...
@@ -408,7 +411,7 @@ Chapter 2. Developer Guide
    1.4. get_route_param( msg, name, val)
    1.5. register_rrcb( callback, param)
-1.1. add_rr_param( msg, param)
+1.1.  add_rr_param( msg, param)
Adds a parameter to the requests's Record-Route URI (param must be in
    ";name=value" format).
@@ -421,7 +424,7 @@ Chapter 2. Developer Guide
      * str* param - parameter to be added to the Record-Route header - it
        must be in ";name=value" format.
-1.2. check_route_param( msg, re)
+1.2.  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
@@ -436,7 +439,7 @@ Chapter 2. Developer Guide
      * regex_t* param - compiled regular expression to be checked against
        the Route header parameters.
-1.3. is_direction( msg, dir)
+1.3.  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
@@ -452,7 +455,7 @@ Chapter 2. Developer Guide
      * int dir - direction to be checked against. It may be
        "RR_FLOW_UPSTREAM" or "RR_FLOW_DOWNSTREAM".
-1.4. get_route_param( msg, name, val)
+1.4.  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
@@ -468,7 +471,7 @@ Chapter 2. Developer Guide
      * 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.5. register_rrcb( callback, param)
+1.5.  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
diff --git a/modules_k/rr/doc/rr_admin.xml b/modules_k/rr/doc/rr_admin.xml
index 296daa4..24dee9b 100644
--- a/modules_k/rr/doc/rr_admin.xml
+++ b/modules_k/rr/doc/rr_admin.xml
@@ -396,9 +396,9 @@ if (check_route_param("nat=yes")) {
    	<title>
    	<function moreinfo="none">is_direction(dir)</function>
    	</title>
-		<para>The function checks the flow direction of the request.
-		As for checking it's used the <quote>ftag</quote> Route header 
-		parameter, the append_fromtag (see <xref linkend="append-fromtag-id"/> 
+		<para>The function checks the flow direction of in-dialog requests.
+		This function uses the <quote>ftag</quote> prameter from the Route header, 
+		therefore the append_fromtag (see <xref linkend="append-fromtag-id"/> 
    	module parameter must be enabled. Also this must be called only after 
    	loose_route() (see <xref linkend="loose-route-id"/>).
    	</para>
@@ -407,16 +407,16 @@ if (check_route_param("nat=yes")) {
    	the request's flow direction.
    	</para>
    	<para>
-		The <quote>downstream</quote> (UAC to UAS) direction is relative to the
-		initial request that created the dialog.
+		The <quote>downstream</quote> direction means that the request is in the same
+		direction as the initial request that created the dialog.
    	</para>
    	<para>Meaning of the parameters is as follows:</para>
    	<itemizedlist>
    	<listitem>
    		<para>
    		<emphasis>dir</emphasis> - string containing the direction to be 
-				checked. It may be <quote>upstream</quote> (from UAS to UAC) or 
-				<quote>downstream</quote> (UAC to UAS).
+				checked. It may be <quote>upstream</quote> (from callee to caller) or 
+				<quote>downstream</quote> (caller to callee).
    		</para>
    	</listitem>
    	</itemizedlist>
@@ -427,8 +427,10 @@ if (check_route_param("nat=yes")) {
    	<title><function>is_direction</function> usage</title>
    	<programlisting format="linespecific">
 ...
-if (is_direction("upstream")) {
-    xdbg("upstream request ($rm)\n");
+if (is_direction("downstream")) {
+    xdbg("in-dialog request from caller to callee (downstream) ($rm)\n");
+} else {
+    xdbg("in-dialog request from callee to caller (upstream) ($rm)\n");
 }
 ...
 </programlisting>

    