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

Module: sip-router Branch: master Commit: a4bdf3c9c951e052b2db1d3967999f662b7438a5 URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=a4bdf3c… Author: Klaus Darilion &lt;klaus.mailinglists(a)pernau.at&gt; Committer: Klaus Darilion &lt;klaus.mailinglists(a)pernau.at&gt; 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>