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

Module: sip-router Branch: master Commit: 37e1fb443f1243125bc1d0c09c5ad8f6d86336d6 URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=37e1fb4… Author: Daniel-Constantin Mierla &lt;miconda(a)gmail.com&gt; Committer: Daniel-Constantin Mierla &lt;miconda(a)gmail.com&gt; 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>