git:master: dispatcher(k): docs update and rebuild readme file - sr-dev

27 Oct 2011

Module: sip-router
Branch: master
Commit: 372b113b6bd4447dfd73b8b6da6a5672730a5636
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=372b113b...
Author: Daniel-Constantin Mierla miconda@gmail.com
Committer: Daniel-Constantin Mierla miconda@gmail.com
Date:   Thu Oct 27 16:07:33 2011 +0200
dispatcher(k): docs update and rebuild readme file
---
modules_k/dispatcher/README                   |   46 ++++++++++++---------
 modules_k/dispatcher/doc/dispatcher_admin.xml |   55 +++++++++++++++---------
 2 files changed, 61 insertions(+), 40 deletions(-)

diff --git a/modules_k/dispatcher/README b/modules_k/dispatcher/README
index 4ee0370..19b17de 100644
--- a/modules_k/dispatcher/README
+++ b/modules_k/dispatcher/README
@@ -751,25 +751,28 @@ ds_select_dst("1", "$var(a)");
4.5. ds_mark_dst([state])
-   Mark the last used address from destination set as inactive
-   ("i"/"I"/"0"), active ("a"/"A"/"1") or probing ("p"/"P"/"2"). With this
-   function, an automatic detection of failed gateways can be implemented.
-   When an address is marked as inactive, it will be ignored by
-   'ds_select_dst' and 'ds_select_domain'.
+   Mark the last used address from destination set as inactive ("i"/"I"),
+   active ("a"/"A"), disabled ("d"/"D") or trying ("t"/"T"). Apart of
+   disabled state, a destination can be set in probing mode by adding
+   ("p"/"P") flag. With this function, an automatic detection of failed
+   gateways can be implemented. When an address is marked as inactive or
+   disabled, it will be ignored by 'ds_select_dst' and 'ds_select_domain'.
The parameter state is optional, when it is missing, then the
    destination will be marked inactive (i.e., same as 'i').
Possible values for state parameter:
-     * "i", "I" or "0" - the last destination should be set to inactive
-       and will be ignored in future requests.
-     * "a", "A" or "1" - the last destination should be set to active and
-       the error-counter should set to "0".
-     * "p", "P" or "2" - the last destination will be set to probing. This
+     * "a" or "A" - the last destination should be set to active and the
+       error-counter should set to "0".
+     * "i" or "I" - the last destination should be set to inactive and
+       will be ignored in future requests.
+     * "t" or "T" - the last destination should be set to temporary trying
+       state and failure counter is incremented. When the failure counter
+       reaches the threshold, the destination will be set inactive.
+     * "p" and "P" - this has to be used in addition to one of the
+       previous flags - the last destination will be set to probing. This
        mean the destination will be pinged with SIP OPTIONS requests from
-       time to time to detect if it is up running or down. Note: You will
-       need to call this function "threshhold"-times, before it will be
-       actually set to probing.
+       time to time to detect if it is up running or down.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
@@ -778,7 +781,7 @@ ds_select_dst("1", "$var(a)");
 failure_route[tryagain] {
 ...
    if(t_check_status("500"))
-      ds_mark_dst("i");
+      ds_mark_dst("ip"); # set to inactive and probing
 ...
 }
 ...
@@ -860,9 +863,10 @@ onreply_route {
      * _state_ : state of the destination address
           + "a": active
           + "i": inactive
+          + "t": trying
           + "d": disabled
-       The states "a" or "i" can be followed by "p" to set probing mode
-       (e.g. 'ap' or 'ip')
+       The states "a", "i" or "t" can be followed by "p" to set probing
+       mode (e.g. 'ap', 'ip' or 'tp').
      * _group_: destination group id
      * _address_: address of the destination in the _group_
@@ -916,14 +920,18 @@ onreply_route {
      * _state_ : state of the destination address
           + "a": active
           + "i": inactive
+          + "t": trying
           + "d": disabled
-       The states "a" or "i" can be followed by "p" to set probing mode
-       (e.g. 'ap' or 'ip')
+       The states "a", "i" or "t" can be followed by "p" to set probing
+       mode (e.g. 'ap', 'ip' or 'tp').
      * _group_: destination group id
      * _address_: address of the destination in the _group_
Example:
-                sercmd dispatcher.set_state _state_ _group_ _address_
+...
+# prototype: sercmd dispatcher.set_state _state_ _group_ _address_
+sercmd dispatcher.set_state ip 2 sip:127.0.0.1:5080
+...
6.2. dispatcher.list
diff --git a/modules_k/dispatcher/doc/dispatcher_admin.xml b/modules_k/dispatcher/doc/dispatcher_admin.xml
index 273c68c..9fc5fdb 100644
--- a/modules_k/dispatcher/doc/dispatcher_admin.xml
+++ b/modules_k/dispatcher/doc/dispatcher_admin.xml
@@ -876,10 +876,11 @@ ds_select_dst("1", "$var(a)");
    	</title>
    	<para>
    	Mark the last used address from destination set as inactive
-		("i"/"I"/"0"), active ("a"/"A"/"1") or probing ("p"/"P"/"2").
-		With this function, an automatic detection of failed gateways
-		can be implemented. When an address is marked as
-		inactive, it will be ignored by 'ds_select_dst' and
+		("i"/"I"), active ("a"/"A"), disabled ("d"/"D") or trying ("t"/"T").
+		Apart of disabled state, a destination can be set in probing mode by
+		adding ("p"/"P") flag. With this function, an automatic detection
+		of failed gateways can be implemented. When an address is marked as
+		inactive or disabled, it will be ignored by 'ds_select_dst' and
    	'ds_select_domain'.
    	</para>
    	<para>
@@ -889,21 +890,28 @@ ds_select_dst("1", "$var(a)");
    	<para>Possible values for state parameter:</para>
    	<itemizedlist>
    	<listitem>
-			<para><emphasis>"i", "I" or "0"</emphasis> - the last destination
+			<para><emphasis>"a" or "A"</emphasis> - the last destination
+				should be set to active and the error-counter should set to "0".
+			</para>
+		</listitem>
+		<listitem>
+			<para><emphasis>"i" or "I"</emphasis> - the last destination
    			should be set to inactive and will be ignored in future
    			requests.</para>
    	</listitem>
    	<listitem>
-			<para><emphasis>"a", "A" or "1"</emphasis> - the last destination
-				should be set to active and the error-counter should set to "0".</para>
+			<para><emphasis>"t" or "T"</emphasis> - the last destination
+				should be set to temporary trying state and failure counter
+				is incremented. When the failure counter reaches the threshold,
+				the destination will be set inactive.
+			</para>
    	</listitem>
    	<listitem>
-			<para><emphasis>"p", "P" or "2"</emphasis> - the last destination
+			<para><emphasis>"p" and "P"</emphasis> - this has to be used in
+				addition to one of the previous flags - the last destination
    			will be set to probing. This mean the destination will be pinged
    			with SIP OPTIONS requests from time to time to detect if it is
-				up running or down. Note: You will need to call this
-				function "threshhold"-times, before it will be actually set
-				to probing.</para>
+				up running or down.</para>
    	</listitem>
    	</itemizedlist>
    	<para>
@@ -916,7 +924,7 @@ ds_select_dst("1", "$var(a)");
 failure_route[tryagain] {
 ...
    if(t_check_status("500"))
-      ds_mark_dst("i");
+      ds_mark_dst("ip"); # set to inactive and probing
 ...
 }
 ...
@@ -1033,11 +1041,12 @@ onreply_route {
    		      <itemizedlist>
                     <listitem><para> <quote>a</quote>: active</para></listitem> 
    		         <listitem><para> <quote>i</quote>: inactive</para></listitem>	
+			         <listitem><para> <quote>t</quote>: trying</para></listitem>	
    		         <listitem><para> <quote>d</quote>: disabled</para></listitem>	
    			  </itemizedlist>
-				  <para>The states <quote>a</quote> or <quote>i</quote> can be
-					  followed by <quote>p</quote> to set probing mode (e.g. 'ap'
-					  or 'ip')</para>
+				  <para>The states <quote>a</quote>, <quote>i</quote> or
+					  <quote>t</quote> can be followed by <quote>p</quote>
+					  to set probing mode (e.g. 'ap', 'ip' or 'tp').</para>
    		</listitem>
<listitem><para>_group_: destination group id</para></listitem>
@@ -1117,11 +1126,12 @@ onreply_route {
    		      <itemizedlist>
                     <listitem><para> <quote>a</quote>: active</para></listitem>
    		         <listitem><para> <quote>i</quote>: inactive</para></listitem>
+			         <listitem><para> <quote>t</quote>: trying</para></listitem>
    		         <listitem><para> <quote>d</quote>: disabled</para></listitem>
    			  </itemizedlist>
-				  <para>The states <quote>a</quote> or <quote>i</quote> can be
-					  followed by <quote>p</quote> to set probing mode (e.g. 'ap'
-					  or 'ip')</para>
+				  <para>The states <quote>a</quote>, <quote>i</quote> or
+					  <quote>t</quote> can be followed by <quote>p</quote>
+					  to set probing mode (e.g. 'ap', 'ip' or 'tp').</para>
    		</listitem>
<listitem><para>_group_: destination group id</para></listitem>
@@ -1131,9 +1141,12 @@ onreply_route {
    	<para>
    	Example:
    	</para>
-        <programlisting  format="linespecific">
-		sercmd dispatcher.set_state _state_ _group_ _address_
-		</programlisting>
+<programlisting  format="linespecific">
+...
+# prototype: sercmd dispatcher.set_state _state_ _group_ _address_
+sercmd dispatcher.set_state ip 2 sip:127.0.0.1:5080
+...
+</programlisting>
     </section>
    <section>
    	<title>

    