sl(k): docs extension, dependency on tm

modules_k/sl/README

@@ -10,131 +10,171 @@ Bogdan Iancu
 
    Copyright © 2003 FhG FOKUS
    Revision History
-   Revision $Revision$ $Date: 2008-08-06 13:08:33 +0300
-                              (Wed, 06 Aug 2008) $
-     __________________________________________________________
+   Revision $Revision$ $Date$
+     __________________________________________________________________
 
    Table of Contents
 
    1. Admin Guide
 
-        1.1. Overview
-        1.2. Dependencies
+        1. Overview
+        2. Dependencies
 
-              1.2.1. Kamailio Modules
-              1.2.2. External Libraries or Applications
+              2.1. Kamailio Modules
+              2.2. External Libraries or Applications
 
-        1.3. Exported Parameters
+        3. Exported Parameters
 
-              1.3.1. enable_stats (integer)
-              1.3.2  bind_tm (integer)
+              3.1. enable_stats (integer)
+              3.2. bind_tm (integer)
 
-        1.4. Exported Functions
+        4. Exported Functions
 
-              1.4.1. sl_send_reply(code, reason)
-              1.4.2. send_reply(code, reason)
-              1.4.3. sl_reply_error()
+              4.1. sl_send_reply(code, reason)
+              4.2. send_reply(code, reason)
+              4.3. sl_reply_error()
 
-        1.5. Exported Statistics
+        5. Exported Statistics
 
-              1.5.1. 1xx_replies
-              1.5.2. 2xx_replies
-              1.5.3. 3xx_replies
-              1.5.4. 4xx_replies
-              1.5.5. 5xx_replies
-              1.5.6. 6xx_replies
-              1.5.7. sent_replies
-              1.5.8. sent_err_replies
-              1.5.9. received_ACKs
+              5.1. 1xx_replies
+              5.2. 2xx_replies
+              5.3. 3xx_replies
+              5.4. 4xx_replies
+              5.5. 5xx_replies
+              5.6. 6xx_replies
+              5.7. sent_replies
+              5.8. sent_err_replies
+              5.9. received_ACKs
 
    List of Examples
 
    1.1. enable_stats example
-   1.2. sl_send_reply usage
-   1.3. send_reply usage
-   1.4. sl_reply_error usage
+   1.2. bind_tm example
+   1.3. sl_send_reply usage
+   1.4. send_reply usage
+   1.5. sl_reply_error usage
 
 Chapter 1. Admin Guide
 
-1.1. Overview
+   Table of Contents
+
+   1. Overview
+   2. Dependencies
+
+        2.1. Kamailio Modules
+        2.2. External Libraries or Applications
+
+   3. Exported Parameters
+
+        3.1. enable_stats (integer)
+        3.2. bind_tm (integer)
+
+   4. Exported Functions
+
+        4.1. sl_send_reply(code, reason)
+        4.2. send_reply(code, reason)
+        4.3. sl_reply_error()
+
+   5. Exported Statistics
 
-   The SL module allows Kamailio 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.
+        5.1. 1xx_replies
+        5.2. 2xx_replies
+        5.3. 3xx_replies
+        5.4. 4xx_replies
+        5.5. 5xx_replies
+        5.6. 6xx_replies
+        5.7. sent_replies
+        5.8. sent_err_replies
+        5.9. received_ACKs
 
-   The SL module needs to filter ACKs sent after a local stateless
-   reply to an INVITE was generated. To recognize such ACKs,
-   Kamailio adds a special "signature" in to-tags. This signature
-   is sought for in incoming ACKs, and if included, the ACKs are
-   absorbed.
+1. Overview
 
-   To speed up the filtering process, the module uses a timeout
-   mechanism. When a reply is sent, a timer is set. As time as the
-   timeout didn't hit, 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 allows Kamailio 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 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 Kamailio want to reply to it. Than, it will keep
-   the current to-tag, which will be mirrored in ACK. Kamailio
-   will not see its signature and forward the ACK downstream.
-   Caused harm is not bad--just a useless ACK is forwarded.
+   The SL module needs to filter ACKs sent after a local stateless reply
+   to an INVITE was generated. To recognize such ACKs, Kamailio adds a
+   special "signature" in to-tags. This signature is sought for in
+   incoming ACKs, and if included, the ACKs are absorbed.
 
-1.2. Dependencies
+   To speed up the filtering process, the module uses a timeout mechanism.
+   When a reply is sent, a timer is set. As time as the timeout didn't
+   hit, 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.1. Kamailio Modules
+   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 Kamailio want
+   to reply to it. Than, it will keep the current to-tag, which will be
+   mirrored in ACK. Kamailio will not see its signature and forward the
+   ACK downstream. Caused harm is not bad--just a useless ACK is
+   forwarded.
+
+2. Dependencies
+
+   2.1. Kamailio Modules
+   2.2. External Libraries or Applications
+
+2.1. Kamailio Modules
 
    The following modules must be loaded before this module:
-     * No dependencies on other Kamailio modules.
+     * TM - transaction module, if you want to use the transactional
+       send_reply functionality.
 
-1.2.2. External Libraries or Applications
+2.2. External Libraries or Applications
 
-   The following libraries or applications must be installed
-   before running Kamailio with this module loaded:
+   The following libraries or applications must be installed before
+   running Kamailio with this module loaded:
      * None.
 
-1.3. Exported Parameters
+3. Exported Parameters
+
+   3.1. enable_stats (integer)
+   3.2. bind_tm (integer)
 
-1.3.1. enable_stats (integer)
+3.1. enable_stats (integer)
 
    If the module should generate and export statistics to the core
    manager. A zero value means disabled.
 
-   SL module provides statistics about how many replies were sent
-   ( splitted per code classes) and how many local ACKs were
-   filtered out.
+   SL module provides statistics about how many replies were sent (
+   splitted per code classes) and how many local ACKs were filtered out.
 
    Default value is 1 (enabled).
 
    Example 1.1. enable_stats example
 modparam("sl", "enable_stats", 0)
 
-1.3.1. bind_tm (integer)
+3.2. bind_tm (integer)
+
+   If the module should use transaction support for sending the replies. A
+   zero value means disabled.
 
-   If the module should use transaction support for sending the 
-   replies. A zero value means disabled.
-   
    Module tm should be loaded before of this one
 
    Default value is 1 (enabled).
 
-   Example 1.1. bind_tm example
+   Example 1.2. bind_tm example
 modparam("sl", "bind_tm", 0)
 
-1.4. Exported Functions
+4. Exported Functions
+
+   4.1. sl_send_reply(code, reason)
+   4.2. send_reply(code, reason)
+   4.3. sl_reply_error()
 
-1.4.1.  sl_send_reply(code, reason)
+4.1.  sl_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. 'code' and 'reason'
-   can contain pseudo-variables that are replaced at runtime.
+   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.
+   'code' and 'reason' can contain pseudo-variables that are replaced at
+   runtime.
 
    Meaning of the parameters is as follows:
      * code - Return code.
@@ -142,20 +182,19 @@ modparam("sl", "bind_tm", 0)
 
    This function can be used from REQUEST_ROUTE, ERROR_ROUTE.
 
-   Example 1.2. sl_send_reply usage
+   Example 1.3. sl_send_reply usage
 ...
 sl_send_reply("404", "Not found");
 ...
 sl_send_reply("$err.rcode", "$err.rreason");
 ...
 
-1.4.2.  send_reply(code, reason)
+4.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 stateful or stateless,
-   depending of the Transaction module: if the transaction for
-   current request has created, then the reply is sent stateful,
-   otherwise stateless.
+   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
+   Transaction module: if the transaction for current request has created,
+   then the reply is sent stateful, otherwise stateless.
 
    Meaning of the parameters is as follows:
      * code - Return code.
@@ -164,60 +203,70 @@ sl_send_reply("$err.rcode", "$err.rreason");
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    BRANCH_ROUTE, ERROR_ROUTE.
 
-   Example 1.3. send_reply usage
+   Example 1.4. send_reply usage
 ...
 send_reply("404", "Not found");
 ...
 send_reply("403", "Invalid user - $fU");
 ...
 
-1.4.3.  sl_reply_error()
+4.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.
 
    This function can be used from REQUEST_ROUTE.
 
-   Example 1.4. sl_reply_error usage
+   Example 1.5. sl_reply_error usage
 ...
 sl_reply_error();
 ...
 
-1.5. Exported Statistics
+5. Exported Statistics
+
+   5.1. 1xx_replies
+   5.2. 2xx_replies
+   5.3. 3xx_replies
+   5.4. 4xx_replies
+   5.5. 5xx_replies
+   5.6. 6xx_replies
+   5.7. sent_replies
+   5.8. sent_err_replies
+   5.9. received_ACKs
 
-1.5.1. 1xx_replies
+5.1. 1xx_replies
 
    The number of 1xx_replies.
 
-1.5.2. 2xx_replies
+5.2. 2xx_replies
 
    The number of 2xx_replies.
 
-1.5.3. 3xx_replies
+5.3. 3xx_replies
 
    The number of 3xx_replies.
 
-1.5.4. 4xx_replies
+5.4. 4xx_replies
 
    The number of 4xx_replies.
 
-1.5.5. 5xx_replies
+5.5. 5xx_replies
 
    The number of 5xx_replies.
 
-1.5.6. 6xx_replies
+5.6. 6xx_replies
 
    The number of 6xx_replies.
 
-1.5.7. sent_replies
+5.7. sent_replies
 
    The number of sent_replies.
 
-1.5.8. sent_err_replies
+5.8. sent_err_replies
 
    The number of sent_err_replies.
 
-1.5.9. received_ACKs
+5.9. received_ACKs
 
    The number of received_ACKs.

modules_k/sl/doc/sl_admin.xml

@@ -55,7 +55,8 @@
 			<itemizedlist>
 			<listitem>
 			<para>
-				<emphasis>No dependencies on other &kamailio; modules</emphasis>.
+				<emphasis>TM - transaction module</emphasis>, if you want
+				to use the transactional send_reply functionality.
 			</para>
 			</listitem>
 			</itemizedlist>