sl: updated module documentation

- missing parameters and functions added to README

modules/sl/README

@@ -1,151 +1,94 @@
-
-sl Module
+1. SL Module
 
 Bogdan Iancu
 
    FhG FOKUS
 
-Edited by
-
-Bogdan Iancu
-
-   Copyright © 2003 FhG FOKUS
-     _________________________________________________________
-
-   Table of Contents
-   1. User's Guide
+Daniel-Constantin Mierla
 
-        1.1. Overview
-        1.2. Dependencies
+   asipto.com
 
-              1.2.1. SER Modules
-              1.2.2. External Libraries or Applications
+   Copyright © 2003 FhG FOKUS
+     __________________________________________________________________
 
-        1.3. Exported Functions
+   1.1. Overview
+   1.2. Functions
 
-              1.3.1. sl_send_reply(code, reason)
-              1.3.2. sl_reply_error()
-
-   2. Developer's Guide
-   3. Frequently Asked Questions
-
-   List of Examples
-   1-1. sl_send_reply usage
-   1-2. sl_reply_error usage
-     _________________________________________________________
-
-Chapter 1. User's Guide
+        1.2.1. sl_send_reply(code, reason)
+        1.2.2. send_reply(code, reason)
+        1.2.3. sl_reply_error()
 
 1.1. Overview
 
-   The SL module allows ser to act as a stateless UA server and
-   generate replies to SIP requests without keeping state. That
-   is beneficial in many scenarios, in which you wish not to
-   burden server's memory and scale well.
-
-   The SL module needs to filter ACKs sent after a local
-   stateless reply to an INVITE was generated. To recognize such
-   ACKs, ser adds a special "signature" in to-tags. This
-   signature is sought for in incoming ACKs, and if included, the
-   ACKs are absorbed.
+   The SL module allows ser to act as a stateless UA server and generate
+   replies to SIP requests without keeping state. That is beneficial in
+   many scenarios, in which you wish not to burden server's memory and
+   scale well.
 
-   To speed up the filtering process, the module uses a timeout
-   mechanism. When a reply is sent, a timer us set. As time as
-   the timer is valid, The incoming ACK requests will be checked
-   using TO tag value Once the timer expires, all the ACK are let
-   through - a long time passed till it sent a reply, so it does
-   not expect any ACK that have to be blocked.
+   The SL module needs to filter ACKs sent after a local stateless reply
+   to an INVITE was generated. To recognize such ACKs, ser adds a special
+   "signature" in to-tags. This signature is sought for in incoming ACKs,
+   and if included, the ACKs are absorbed.
 
-   The ACK filtering may fail in some rare cases. If you think
-   these matter to you, better use stateful processing (tm
-   module) for INVITE processing. Particularly, the problem
-   happens when a UA sends an INVITE which already has a to-tag
-   in it (e.g., a re-INVITE) and SER want to reply to it. Than,
-   it will keep the current to-tag, which will be mirrored in
-   ACK. SER will not see its signature and forward the ACK
-   downstream. Caused harm is not bad--just a useless ACK is
-   forwarded.
-     _________________________________________________________
+   To speed up the filtering process, the module uses a timeout mechanism.
+   When a reply is sent, a timer us set. As time as the timer is valid,
+   The incoming ACK requests will be checked using TO tag value Once the
+   timer expires, all the ACK are let through - a long time passed till it
+   sent a reply, so it does not expect any ACK that have to be blocked.
 
-1.2. Dependencies
+   The ACK filtering may fail in some rare cases. If you think these
+   matter to you, better use stateful processing (tm module) for INVITE
+   processing. Particularly, the problem happens when a UA sends an INVITE
+   which already has a to-tag in it (e.g., a re-INVITE) and SER want to
+   reply to it. Than, it will keep the current to-tag, which will be
+   mirrored in ACK. SER will not see its signature and forward the ACK
+   downstream. Caused harm is not bad--just a useless ACK is forwarded.
 
-1.2.1. SER Modules
+1.2. Functions
 
-   The following modules must be loaded before this module:
+1.2.1.  sl_send_reply(code, reason)
 
-     * No dependencies on other SER modules.
-     _________________________________________________________
+   For the current request, a reply is sent back having the given code and
+   text reason. The reply is sent stateless, totally independent of the
+   Transaction module and with no retransmission for the INVITE's replies.
 
-1.2.2. External Libraries or Applications
-
-   The following libraries or applications must be installed
-   before running SER with this module loaded:
-
-     * None.
-     _________________________________________________________
+   Meaning of the parameters is as follows:
+     * code - Return code.
+     * reason - Reason phrase.
 
-1.3. Exported Functions
+   Example 1. sl_send_reply usage
+...
+sl_send_reply("404", "Not found");
+...
 
-1.3.1. sl_send_reply(code, reason)
+1.2.2.  send_reply(code, reason)
 
-   For the current request, a reply is sent back having the given
-   code and text reason. The reply is sent stateless, totally
-   independent of the Transaction module and with no
-   retransmission for the INVITE's replies.
+   For the current request, a reply is sent back having the given code and
+   text reason. The reply is sent stateful or stateless, depending of the
+   TM module: if the transaction for current request is created, then the
+   reply is sent stateful, otherwise stateless.
 
    Meaning of the parameters is as follows:
-
      * code - Return code.
      * reason - Reason phrase.
 
-   Example 1-1. sl_send_reply usage
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
+   BRANCH_ROUTE.
+
+   Example 2. send_reply usage
 ...
-sl_send_reply("404", "Not found");
+send_reply("404", "Not found");
+...
+send_reply("403", "Invalid user - $fU");
 ...
-     _________________________________________________________
 
-1.3.2. sl_reply_error()
+1.2.3.  sl_reply_error()
 
-   Sends back an error reply describing the nature of the last
-   internal error. Usually this function should be used after a
-   script function that returned an error code.
+   Sends back an error reply describing the nature of the last internal
+   error. Usually this function should be used after a script function
+   that returned an error code.
 
-   Example 1-2. sl_reply_error usage
+   Example 3. sl_reply_error usage
 ...
 sl_reply_error();
 ...
-     _________________________________________________________
-
-Chapter 2. Developer's Guide
-
-   The module does not provide any sort of API to use in other
-   SER modules.
-     _________________________________________________________
-
-Chapter 3. Frequently Asked Questions
-
-   3.1. Where can I find more about SER?
-   3.2. Where can I post a question about this module?
-   3.3. How can I report a bug?
-
-   3.1. Where can I find more about SER?
-
-   Take a look at http://iptel.org/ser.
-
-   3.2. Where can I post a question about this module?
-
-   First at all check if your question was already answered on
-   one of our mailing lists:
-
-     * http://mail.iptel.org/mailman/listinfo/serusers
-     * http://mail.iptel.org/mailman/listinfo/serdev
-
-   E-mails regarding any stable version should be sent to
-   <[email protected]> and e-mail regarding development versions
-   or CVS snapshots should be send to <[email protected]>.
-
-
-   3.3. How can I report a bug?
-
-   Please follow the guidelines provided at:
-   http://iptel.org/ser/bugs

modules/sl/doc/functions.xml

@@ -3,14 +3,6 @@
    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
 <section id="sl.functions" xmlns:xi="http://www.w3.org/2001/XInclude">
-    <sectioninfo>
-	<revhistory>
-	    <revision>
-		<revnumber>$Revision$</revnumber>
-		<date>$Date$</date>
-	    </revision>
-	</revhistory>
-    </sectioninfo>
 
     <title>Functions</title>
 
@@ -45,6 +37,43 @@ sl_send_reply("404", "Not found");
 	</example>
     </section>
     
+	<section id="send_reply">
+		<title>
+		<function moreinfo="none">send_reply(code, reason)</function>
+		</title>
+		<para>
+		For the current request, a reply is sent back having the given code 
+		and text reason. The reply is sent stateful or stateless, depending of 
+		the TM module: if the transaction for current request is
+		created, then the reply is sent stateful, otherwise stateless.
+		</para>
+		<para>Meaning of the parameters is as follows:</para>
+		<itemizedlist>
+		<listitem>
+			<para><emphasis>code</emphasis> - Return code.
+			</para>
+		</listitem>
+		<listitem>
+			<para><emphasis>reason</emphasis> - Reason phrase.
+			</para>
+		</listitem>
+		</itemizedlist>
+		<para>
+			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
+			BRANCH_ROUTE.
+		</para>
+		<example>
+		<title><function>send_reply</function> usage</title>
+		<programlisting format="linespecific">
+...
+send_reply("404", "Not found");
+...
+send_reply("403", "Invalid user - $fU");
+...
+</programlisting>
+		</example>
+	</section>
+
     <section id="sl_reply_error">
 	<title>
 	    <function>sl_reply_error()</function>

modules/sl/doc/params.xml

@@ -3,15 +3,56 @@
    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
 <section id="sl.parameters" xmlns:xi="http://www.w3.org/2001/XInclude">
-    <sectioninfo>
-	<revhistory>
-	    <revision>
-		<revnumber>$Revision$</revnumber>
-		<date>$Date$</date>
-	    </revision>
-	</revhistory>
-    </sectioninfo>
 
     <title>Parameters</title>
 
+	<section id="default_code">
+		<title><varname>default_code</varname> (int)</title>
+		<para>
+		Default reply status code.
+		</para>
+		<para>
+		Default value is 500.
+		</para>
+		<example>
+		<title>default_code example</title>
+		<programlisting format="linespecific">
+modparam("sl", "default_code", 505)
+</programlisting>
+		</example>
+	</section>
+
+	<section id="default_reason">
+		<title><varname>default_reason</varname> (str)</title>
+		<para>
+		Default reply reason phrase.
+		</para>
+		<para>
+		Default value is 'Internal Server Error'.
+		</para>
+		<example>
+		<title>default_reason example</title>
+		<programlisting format="linespecific">
+modparam("sl", "default_reason", "Server Error")
+</programlisting>
+		</example>
+	</section>
+
+	<section id="bind_tm">
+		<title><varname>bind_tm</varname> (int)</title>
+		<para>
+		Controls if SL module should attempt to bind to TM module in order
+		to send stateful reply when the transaction is created.
+		</para>
+		<para>
+		Default value is 1 (enabled).
+		</para>
+		<example>
+		<title>bind_tm example</title>
+		<programlisting format="linespecific">
+modparam("sl", "bind_tm", 0)  # feature disabled
+</programlisting>
+		</example>
+	</section>
+
 </section>

modules/sl/doc/sl.xml

@@ -13,18 +13,19 @@
 		    <email>[email protected]</email>
 		</address>
 	    </author>
+	    <author>
+		<firstname>Daniel-Constantin</firstname>
+		<surname>Mierla</surname>
+		<affiliation><orgname>asipto.com</orgname></affiliation>
+		<address>
+		    <email>[email protected]</email>
+		</address>
+	    </author>
 	</authorgroup>
 	<copyright>
 	    <year>2003</year>
 	    <holder>FhG FOKUS</holder>
 	</copyright>
-	<revhistory>
-	    <revision>
-		<revnumber>$Revision$</revnumber>
-		<date>$Date$</date>
-	    </revision>
-	</revhistory>
-
     </sectioninfo>
 
     <title>SL Module</title>

modules/sl/sl.c

@@ -108,7 +108,7 @@ static cmd_export_t cmds[]={
 static param_export_t params[] = {
 	{"default_code",   PARAM_INT, &default_code},
 	{"default_reason", PARAM_STR, &default_reason},
-	{ "bind_tm",       PARAM_INT, &sl_bind_tm },
+	{"bind_tm",        PARAM_INT, &sl_bind_tm},
 
     {0, 0, 0}
 };