[sr-dev] git:master: improve documentation of is_direction() function
Klaus Darilion
klaus.mailinglists at pernau.at
Wed Sep 8 14:59:37 CEST 2010
Module: sip-router
Branch: master
Commit: a4bdf3c9c951e052b2db1d3967999f662b7438a5
URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=a4bdf3c9c951e052b2db1d3967999f662b7438a5
Author: Klaus Darilion <klaus.mailinglists at pernau.at>
Committer: Klaus Darilion <klaus.mailinglists at 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>
More information about the sr-dev
mailing list