dispatcher(k): docs update and rebuild readme file

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
 

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>