[sr-dev] git:andrei/blst_send_flags: blst: docs for blst_{set, clear}_ignore script functions

[Andrei Pelinescu-Onciul]

Module: sip-router
Branch: andrei/blst_send_flags
Commit: d322fc29ab9a5edce1f826de2a5de141aab09e1f
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=d322fc29ab9a5edce1f826de2a5de141aab09e1f

Author: Andrei Pelinescu-Onciul <andrei at iptel.org>
Committer: Andrei Pelinescu-Onciul <andrei at iptel.org>
Date:   Wed Dec 23 18:13:35 2009 +0100

blst: docs for blst_{set,clear}_ignore script functions

---

 modules_s/blst/README            |   47 ++++++++++++++++++++++
 modules_s/blst/doc/functions.xml |   80 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 127 insertions(+), 0 deletions(-)

diff --git a/modules_s/blst/README b/modules_s/blst/README
index 8387e98..44b966e 100644
--- a/modules_s/blst/README
+++ b/modules_s/blst/README
@@ -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
diff --git a/modules_s/blst/doc/functions.xml b/modules_s/blst/doc/functions.xml
index a26f8b8..86bd87b 100644
--- a/modules_s/blst/doc/functions.xml
+++ b/modules_s/blst/doc/functions.xml
@@ -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>