[sr-dev] git:master: dispatcher: extended the documentation for ds_is_from_list()
Daniel-Constantin Mierla
miconda at gmail.com
Fri Sep 5 17:46:59 CEST 2014
Module: sip-router
Branch: master
Commit: 37e1fb443f1243125bc1d0c09c5ad8f6d86336d6
URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=37e1fb443f1243125bc1d0c09c5ad8f6d86336d6
Author: Daniel-Constantin Mierla <miconda at gmail.com>
Committer: Daniel-Constantin Mierla <miconda at 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>
More information about the sr-dev
mailing list