blst: docs for blst_{set,clear}_ignore script functions
authorAndrei Pelinescu-Onciul <andrei@iptel.org>
Wed, 23 Dec 2009 17:13:35 +0000 (18:13 +0100)
committerAndrei Pelinescu-Onciul <andrei@iptel.org>
Wed, 23 Dec 2009 17:13:35 +0000 (18:13 +0100)
modules_s/blst/README
modules_s/blst/doc/functions.xml

index 8387e98..44b966e 100644 (file)
@@ -16,6 +16,11 @@ Andrei Pelinescu-Onciul
         1.2.2. blst_add_retry_after(min, max)
         1.2.3. blst_del()
         1.2.4. blst_is_blacklisted()
+        1.2.5. blst_set_ignore() blst_set_ignore(flags)
+                blst_rpl_set_ignore() blst_rpl_set_ignore(flags)
+
+        1.2.6. blst_clear_ignore() blst_clear_ignore(flags)
+                blst_rpl_clear_ignore() blst_rpl_clear_ignore(flags)
 
 1.1. Overview
 
@@ -80,3 +85,45 @@ if (msg_status==503){ # blacklist 503 source for Retry-After seconds
         drop;
    }
 ...
+
+1.2.5.  blst_set_ignore() blst_set_ignore(flags) blst_rpl_set_ignore()
+blst_rpl_set_ignore(flags)
+
+   Set errors that will not be taken into account when deciding whether or
+   not to blacklist a destination for the current message or a local reply
+   to the current message.
+
+   blst_set_ignore(..) works for forwarding the current message and
+   blst_rpl_set_ignore(...) works for local replies to the current
+   message.
+
+   The variants with no parameters will ignore everything (equivalent with
+   passing 0xff).
+
+   The following flags are defined:
+     * 0x02 - generic send error (send denied/ failed).
+     * 0x04 - connect failed (TCP, TLS or SCTP).
+     * 0x08 - ICMP error (not currently used).
+     * 0x10 - SIP transaction timeout.
+     * 0x20 - 503 reply (statefull mode only). For more details see
+       tmblst_503.
+
+Note
+
+   TCP and TLS send and connect errors are handled per connection and not
+   per message. The connection blacklist ignore flags are inherithed from
+   the message that caused the connection establishment.
+
+   Example 5. blst_set_ignore usage
+    blst_set_ignore(6); # ignore send and connect errors
+
+1.2.6.  blst_clear_ignore() blst_clear_ignore(flags) blst_rpl_clear_ignore()
+blst_rpl_clear_ignore(flags)
+
+   Clears blacklist ignore flags previously set by the corresponding
+   blst_set_ignore(...) or blst_rpl_set_ignore(...) functions.
+
+   See also blst_set_ignore.
+
+   Example 6. blst_clear_ignore usage
+    blst_clear_ignore(4); # ignore connect errors
index a26f8b8..86bd87b 100644 (file)
@@ -108,4 +108,84 @@ if (msg_status==503){ # blacklist 503 source for Retry-After seconds
        </example>
     </section>
 
+       <section id="blst_set_ignore">
+       <title>
+               <function>blst_set_ignore()</function>
+               <function>blst_set_ignore(flags)</function>
+               <function>blst_rpl_set_ignore()</function>
+               <function>blst_rpl_set_ignore(flags)</function>
+       </title>
+       <para>
+               Set errors that will not be taken into account when deciding
+               whether or not to blacklist a destination for the current message
+               or a local reply to the current message.
+       </para>
+       <para>
+               <function>blst_set_ignore(..)</function> works for forwarding the
+               current message and <function>blst_rpl_set_ignore(...)</function>
+               works for local replies to the current message.
+       </para>
+       <para>
+               The variants with no parameters will ignore everything (equivalent
+               with passing 0xff).
+       </para>
+       <para>
+               The following flags are defined:
+               <itemizedlist>
+                       <listitem>
+                               <emphasis>0x02</emphasis> - generic send error (send denied/
+                                failed).
+                       </listitem>
+                       <listitem>
+                               <emphasis>0x04</emphasis> - connect failed (TCP, TLS or SCTP).
+                       </listitem>
+                       <listitem>
+                               <emphasis>0x08</emphasis> - ICMP error (not currently used).
+                       </listitem>
+                       <listitem>
+                               <emphasis>0x10</emphasis> - SIP transaction timeout.
+                       </listitem>
+                       <listitem>
+                               <emphasis>0x20</emphasis> - 503 reply (statefull mode only).
+                               For more details see <emphasis>tm</emphasis>
+                               <varname>blst_503</varname>.
+                       </listitem>
+               </itemizedlist>
+       </para>
+       <note>
+               TCP and TLS send and connect errors are handled per connection and
+               not per message. The connection blacklist ignore flags are inherithed
+               from the message that caused the connection establishment.
+       </note>
+       <example>
+               <title><function>blst_set_ignore</function> usage</title>
+               <programlisting>
+    blst_set_ignore(6); # ignore send and connect errors
+               </programlisting>
+       </example>
+       </section>
+
+       <section id="blst_clear_ignore">
+       <title>
+               <function>blst_clear_ignore()</function>
+               <function>blst_clear_ignore(flags)</function>
+               <function>blst_rpl_clear_ignore()</function>
+               <function>blst_rpl_clear_ignore(flags)</function>
+       </title>
+       <para>
+               Clears blacklist ignore flags previously set by the corresponding
+               <function>blst_set_ignore(...)</function> or
+               <function>blst_rpl_set_ignore(...)</function> functions.
+       </para>
+       <para>
+               See also <function>blst_set_ignore</function>.
+       </para>
+       <example>
+               <title><function>blst_clear_ignore</function> usage</title>
+           <programlisting>
+    blst_clear_ignore(4); # ignore connect errors
+               </programlisting>
+       </example>
+       </section>
+
 </section>