git:master: dispatcher: extended the documentation for ds_is_from_list() - sr-dev

5 Sep 2014

Module: sip-router
Branch: master
Commit: 37e1fb443f1243125bc1d0c09c5ad8f6d86336d6
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=37e1fb44...
Author: Daniel-Constantin Mierla miconda@gmail.com
Committer: Daniel-Constantin Mierla miconda@gmail.com
Date:   Fri Sep  5 17:46:14 2014 +0200
dispatcher: extended the documentation for ds_is_from_list()
---
modules/dispatcher/README                   |   56 +++++++++++++++++++------
 modules/dispatcher/doc/dispatcher_admin.xml |   58 ++++++++++++++++++++++----
 2 files changed, 91 insertions(+), 23 deletions(-)

diff --git a/modules/dispatcher/README b/modules/dispatcher/README
index 50b7d1b..a6dd931 100644
--- a/modules/dispatcher/README
+++ b/modules/dispatcher/README
@@ -72,7 +72,7 @@ Carsten Bock
               4.3. ds_next_dst()
               4.4. ds_next_domain()
               4.5. ds_mark_dst([state])
-              4.6. ds_is_from_list([groupid])
+              4.6. ds_is_from_list([groupid [, uri, mode] ])
               4.7. ds_load_update()
               4.8. ds_load_unset()
@@ -188,7 +188,7 @@ Chapter 1. Admin Guide
         4.3. ds_next_dst()
         4.4. ds_next_domain()
         4.5. ds_mark_dst([state])
-        4.6. ds_is_from_list([groupid])
+        4.6. ds_is_from_list([groupid [, uri, mode] ])
         4.7. ds_load_update()
         4.8. ds_load_unset()
@@ -695,7 +695,7 @@ Note
    4.3. ds_next_dst()
    4.4. ds_next_domain()
    4.5. ds_mark_dst([state])
-   4.6. ds_is_from_list([groupid])
+   4.6. ds_is_from_list([groupid [, uri, mode] ])
    4.7. ds_load_update()
    4.8. ds_load_unset()
@@ -834,25 +834,53 @@ failure_route[tryagain] {
 }
 ...
-4.6. ds_is_from_list([groupid])
-
-   This function returns true, if the current request comes from a host in
-   the given group of the dispatcher-list; otherwise false.
-
-   Parameter groupid is optional, when it is missing, then the matching
-   will be done against all addresses in all groups. Upon a match, the
-   variable specified by 'setid_pvname' parameter will be set to groupid
-   of matching address and the attributes will be set in variable
-   specified by 'attrs_pvname'. The parameter can be an integer or a
-   variable holding an integer value.
+4.6. ds_is_from_list([groupid [, uri, mode] ])
+
+   This function returns true, if there is a match of source address or
+   uri with an address in the given group of the dispatcher-list;
+   otherwise false.
+
+   Description of parameters:
+     * groupid (optional) - if not given or its value is -1, the matching
+       will be done over all addresses in all dispacher groups. Otherwise
+       the matching will be done only against the addresses in the
+       specific group id. The parameter can be an integer or a variable
+       holding an integer value.
+     * uri (optional) - if is empty or missing, the matching is done
+       against source IP, port and protocol. Otherwise the value has to be
+       a valid SIP URI, used to match against addresses in the dispatcher
+       list. Only IP, port and protocol are matches, any additional
+       parameters are ignored. The parameter can be a static or dynamic
+       (with variables) string. The domain part of the URI can be an IP
+       address or a hostname.
+     * mode - (optional) - a bitmask to specify how the matching should be
+       done. If is 0, all ip, port and proto are matched. If bit one is
+       set, then port is ignored. If bit two is set, then protocol is
+       ignored. The parameter can be an integer or a variable holding an
+       integer value. It must be provided if the uri parameter is
+       provided.
+
+   Upon a match, the variable specified by 'setid_pvname' parameter will
+   be set to groupid of matching address and the attributes will be set in
+   variable specified by 'attrs_pvname'.
+
+   Note that for backward compatibility mode, when no parameter is given
+   or only groupid is given, the matching is done only for IP address and
+   port (protocol is ignored).
This function can be used from ANY_ROUTE.
Example 1.33. ds_mark_dst usage
 ...
+if(ds_is_from_list()) {
+    ...
+}
 if(ds_is_from_list("10")) {
     ...
 }
+if(ds_is_from_list("10", "sip:127.0.0.1:5080", "3")) {
+    ...
+}
 ...
4.7. ds_load_update()
diff --git a/modules/dispatcher/doc/dispatcher_admin.xml b/modules/dispatcher/doc/dispatcher_admin.xml
index 75031f9..5177a12 100644
--- a/modules/dispatcher/doc/dispatcher_admin.xml
+++ b/modules/dispatcher/doc/dispatcher_admin.xml
@@ -994,19 +994,53 @@ failure_route[tryagain] {
    </section>
    <section  id="dispatcher.f.ds_is_from_list">
    	<title>
- 		<function moreinfo="none">ds_is_from_list([groupid])</function>
+		<function moreinfo="none">ds_is_from_list([groupid [, uri, mode] ])</function>
    	</title>
    	<para>
-		This function returns true, if the current request comes from a host
-		in the given group of the dispatcher-list; otherwise false.
+		This function returns true, if there is a match of source address or uri
+		with an address in the given group of the dispatcher-list; otherwise false.
+		</para>
+		<para>Description of parameters:</para>
+		<itemizedlist>
+		<listitem>
+			<para><emphasis>groupid</emphasis> (optional) - if not given or its
+				value is -1, the matching will be done over all addresses in
+				all dispacher groups. Otherwise the matching will be done only
+				against the addresses in the specific group id. The parameter
+				can be an integer or a variable holding an integer value.
+			</para>
+		</listitem>
+		<listitem>
+			<para><emphasis>uri</emphasis> (optional) - if is empty or missing,
+				the matching is done against source IP, port and protocol.
+				Otherwise the value has to be a valid SIP URI, used to match
+				against addresses in the dispatcher list. Only IP, port and
+				protocol are matches, any additional parameters are ignored.
+				The parameter can be a static or dynamic (with variables)
+				string. The domain part of the URI can be an IP address or
+				a hostname.
+			</para>
+		</listitem>
+		<listitem>
+			<para><emphasis>mode</emphasis> - (optional) - a bitmask to specify
+				how the matching should be done. If is 0, all ip, port and
+				proto are matched. If bit one is set, then port is ignored.
+				If bit two is set, then protocol is ignored. The parameter
+				can be an integer or a variable holding an integer value.
+				It must be provided if the uri parameter is provided.
+			</para>
+		</listitem>
+		</itemizedlist>
+
+		<para>
+		Upon a match, the variable specified by 'setid_pvname' parameter will
+		be set to groupid of matching address and the attributes will be set in
+		variable specified by 'attrs_pvname'.
    	</para>
    	<para>
-		Parameter groupid is optional, when it is missing, then the matching
-		will be done against all addresses in all groups. Upon a match, the
-		variable specified by 'setid_pvname' parameter will be set to groupid
-		of matching address and the attributes will be set in variable
-		specified by 'attrs_pvname'. The parameter can be an integer or a
-		variable holding an integer value.
+		Note that for backward compatibility mode, when no parameter is given
+		or only groupid is given, the matching is done only for IP address
+		and port (protocol is ignored).
    	</para>
    	<para>
    		This function can be used from ANY_ROUTE.
@@ -1015,9 +1049,15 @@ failure_route[tryagain] {
    	<title><function>ds_mark_dst</function> usage</title>
    	<programlisting format="linespecific">
 ...
+if(ds_is_from_list()) {
+    ...
+}
 if(ds_is_from_list("10")) {
     ...
 }
+if(ds_is_from_list("10", "sip:127.0.0.1:5080", "3")) {
+    ...
+}
 ...
 </programlisting>
    	</example>

    