Fixing documentation

modules_k/sst/README

@@ -10,38 +10,37 @@ Ron Winacott
 
    Copyright © 2006 SOMA Networks, Inc.
    Revision History
-   Revision $Revision$ $Date: 2008-08-06 12:08:33 +0200
-                              (Mi, 06 Aug 2008) $
-     __________________________________________________________
+   Revision $Revision$ $Date$
+     __________________________________________________________________
 
    Table of Contents
 
    1. Admin Guide
 
-        1.1. Overview
-        1.2. How it works
-        1.3. Dependencies
+        1. Overview
+        2. How it works
+        3. Dependencies
 
-              1.3.1. Kamailio Modules
-              1.3.2. External Libraries or Applications
+              3.1. Kamailio Modules
+              3.2. External Libraries or Applications
 
-        1.4. Exported Parameters
+        4. Exported Parameters
 
-              1.4.1. enable_stats (integer)
-              1.4.2. min_se (integer)
-              1.4.3. timeout_avp (string)
-              1.4.4. reject_to_small (integer)
-              1.4.5. sst_flag (integer)
+              4.1. enable_stats (integer)
+              4.2. min_se (integer)
+              4.3. timeout_avp (string)
+              4.4. reject_to_small (integer)
+              4.5. sst_flag (integer)
 
-        1.5. Exported Functions
+        5. Exported Functions
 
-              1.5.1. sstCheckMin(send_reply_flag)
+              5.1. sstCheckMin(send_reply_flag)
 
-        1.6. Exported Statistics
+        6. Exported Statistics
 
-              1.6.1. expired_sst
+              6.1. expired_sst
 
-        1.7. Installation and Running
+        7. Installation and Running
 
    List of Examples
 
@@ -55,42 +54,73 @@ Ron Winacott
 
 Chapter 1. Admin Guide
 
-1.1. Overview
+   Table of Contents
+
+   1. Overview
+   2. How it works
+   3. Dependencies
+
+        3.1. Kamailio Modules
+        3.2. External Libraries or Applications
+
+   4. Exported Parameters
+
+        4.1. enable_stats (integer)
+        4.2. min_se (integer)
+        4.3. timeout_avp (string)
+        4.4. reject_to_small (integer)
+        4.5. sst_flag (integer)
+
+   5. Exported Functions
+
+        5.1. sstCheckMin(send_reply_flag)
+
+   6. Exported Statistics
+
+        6.1. expired_sst
 
-   The sst module provides a way to update the dialog expire timer
-   based on the SIP INVITE/200 OK Session-Expires header value.
-   You can use the sst module in an Kamailio proxy to allow
-   freeing of local resources of dead (expired) calls.
+   7. Installation and Running
 
-   You can also use the sst module to validate the MIN_SE header
-   value and reply to any request with a "422 - Session Timer Too
-   Small" if the value is too small for your Kamailio
-   configuration.
+1. Overview
 
-1.2. How it works
+   SIP session timers are used to make sure that a session (dialog) is
+   still alive, even though there may have been a long time since the last
+   in-dialog message. If the other end is not responding, the dialog will
+   be hung up automatically. SIP session timers need to be supported by
+   all end points for it to work. It's a SIP extension, standardized by
+   the IETF.
 
-   The sst module uses the dialog module to be notified of any new
-   or updated dialogs. It will then look for and extract the
-   session-expire: header value (if there is one) and override the
-   dialog expire timer value for the current context dialog by
-   setting the avp value.
+   The sst module provides a way to update the dialog expiry timer based
+   on the SIP INVITE/200 OK Session-Expires header value. You can use the
+   sst module in an Kamailio proxy to allow freeing of local resources of
+   dead calls.
 
-   You flag any call setup INVITE that you want to cause a timed
-   session to be established. This will cause Kamailio to request
-   the use of session times if the UAC does not request it.
+   You can also use the sst module to validate the MIN_SE header value and
+   reply to any request with a "422 - Session Timer Too Small" if the
+   value is too small for your Kamailio configuration.
 
-   All of this happens with a properly configured dialog and sst
-   module and setting the dialog flag and the sst flag at the time
-   any INVITE sip message is seen. There is no kamailio.cfg script
-   function call required to set the dialog expire timeout value.
-   See the dialog module users guide for more information.
+2. How it works
 
-   The sstCheckMin() script function can be used to varify the
-   Session-expires / MIN-SE header field values are not too small
-   for a proxy. If the SST min_se parameter value is smaller then
-   the messages Session-Expires / MIN-SE values, the test will
-   return true. You can also configure the function to send the
-   422 response for you.
+   The sst module uses the "dialog module" to be notified of any new or
+   updated dialogs. It will then look for and extract the session-expire:
+   header value (if there is one) and override the dialog expire timer
+   value for the current context dialog by setting the avp value.
+
+   You flag any call setup INVITE that you want to cause a timed session
+   to be established. This will cause Kamailio to request the use of
+   session timers if the UAC does not request it.
+
+   All of this happens with a properly configured dialog and sst module
+   and setting the dialog flag and the sst flag at the time any INVITE sip
+   message is seen. There is no kamailio.cfg script function call required
+   to set the dialog expire timeout value. See the "dialog module" users
+   guide for more information.
+
+   The "sstCheckMin()" script function can be used to verify that the
+   Session-expires / MIN-SE header field values are not too small for your
+   server. If the SST min_se parameter value is smaller than the messages
+   Session-Expires / MIN-SE values, the test will return true. You can
+   also configure the function to send the 422 error response for you.
 
    The following was taken from the RFC as a call flow example:
 
@@ -134,28 +164,36 @@ Chapter 1. Admin Guide
     |            |               |
  ...
 
-1.3. Dependencies
+3. Dependencies
+
+   3.1. Kamailio Modules
+   3.2. External Libraries or Applications
 
-1.3.1. Kamailio Modules
+3.1. Kamailio Modules
 
    The following modules must be loaded before this module:
-     * dialog - dialog module and its decencies. (tm)
+     * dialog - dialog module and its dependencies. (tm)
      * sl - stateless module.
 
-1.3.2. External Libraries or Applications
+3.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.4. Exported Parameters
+4. Exported Parameters
 
-1.4.1. enable_stats (integer)
+   4.1. enable_stats (integer)
+   4.2. min_se (integer)
+   4.3. timeout_avp (string)
+   4.4. reject_to_small (integer)
+   4.5. sst_flag (integer)
 
-   If the statistics support should be enabled or not. Via
-   statistic variables, the module provide information about the
-   dialog processing. Set it to zero to disable or to non-zero to
-   enable it.
+4.1. enable_stats (integer)
+
+   If the statistics support should be enabled or not. Via statistic
+   variables, the module provide information about the dialog processing.
+   Set it to zero to disable or to non-zero to enable it.
 
    Default value is "1" (enabled).
 
@@ -164,15 +202,15 @@ Chapter 1. Admin Guide
 modparam("sst", "enable_stats", 0)
 ...
 
-1.4.2. min_se (integer)
+4.2. min_se (integer)
 
-   The value is used to set the proxies MIN-SE value and is used
-   in the 422 reply as the proxies MIN-SE: header value if the
-   sstCheckMin() flag is set to true and the check fails.
+   The value is used to set the proxies MIN-SE value and is used in the
+   422 error reply as the proxys MIN-SE: header value if the
+   "sstCheckMin()" flag is set to true and the check fails.
 
-   If not set and sstCheckMin() is called with the send-reply flag
-   set to true, the default 1800 seconds will be used as the
-   compare and the MIN-SE: header value if the 422 reply is sent.
+   If not set and "sstCheckMin()" is called with the send-reply flag set
+   to true, the default 1800 seconds will be used as the compare and the
+   MIN-SE: header value if the 422 reply is sent.
 
    Default value is "1800" seconds.
 
@@ -181,13 +219,13 @@ modparam("sst", "enable_stats", 0)
 modparam("sst", "min_se", 2400)
 ...
 
-1.4.3. timeout_avp (string)
+4.3. timeout_avp (string)
 
-   This parameter MUST be set to the same value as the dialog
-   parameter of the same name. If this parameter is NOT set, the
-   sst module will not do anything!
+   This parameter MUST be set to the same value as the dialog module
+   parameter of the same name. If this parameter is NOT set, the sst
+   module will not do anything!
 
-   This is how the sst module knows which avp in the dialog module
+   This is how the sst module knows which avp in the dialog module it has
    to change with the new expire value.
 
    Default value is "NULL!" it is not set by default.
@@ -199,18 +237,17 @@ modparam("dialog", "timeout_avp", "$avp(i:10)")
 modparam("sst", "timeout_avp", "$avp(i:10)")
 ...
 
-1.4.4. reject_to_small (integer)
+4.4. reject_to_small (integer)
 
-   In the initial INVITE if the UAC has requested a
-   Session-Expire: and it's value is smaller then our local
-   policies Min-SE (see min_se above), then the PROXY has the
-   right to reject the call by replying to the message with a 422
-   Session Timer Too Small and state our local Min-SE: value. The
-   INVITE is NOT forwarded on through the PROXY.
+   In the initial INVITE if the UAC has requested a Session-Expire: and
+   it's value is smaller than our local policies Min-SE (see min_se
+   above), then the proxy has the right to reject the call by replying to
+   the message with a "422 Session Timer Too Small" and state our local
+   Min-SE: value. The INVITE is NOT forwarded on through the proxy.
 
-   This flag if true will tell the SST module to reject the INVITE
-   with a 422 response. If false, the INVITE is forwarded through
-   the PROXY with out any modifications.
+   If this flag is true, the SST module to reject the INVITE with a 422
+   response. If false, the INVITE is forwarded through the PROXY without
+   any modifications.
 
    Default value is "1" (true/on).
 
@@ -219,20 +256,19 @@ modparam("sst", "timeout_avp", "$avp(i:10)")
 modparam("sst", "reject_to_small", 0)
 ...
 
-1.4.5. sst_flag (integer)
+4.5. sst_flag (integer)
 
-   Keeping with Kamailio, the module will not do anything to any
-   message unless instructed to do so via the kamailio.cfg script.
-   You must set the sst_flag value in the setflag() call of the
-   INVITE you want the sst module to process. But before you can
-   do that, you need to tell the sst module which flag value you
-   are assigning to sst.
+   Keeping with Kamailio, the module will not do anything to any message
+   unless instructed to do so via the kamailio.cfg script. You must set
+   the sst_flag value in the setflag() call of the INVITE you want the sst
+   module to process. But before you can do that, you need to tell the sst
+   module which flag value you are assigning to sst.
 
-   In most cases when ever you set the dialog flag you will want
-   to set the sst flag. If the dialog flag is not set and the sst
-   flag is set, it will not have any effect.
+   In most cases whenever you set the dialog flag you will want to set the
+   sst flag. If the dialog flag is not set and the sst flag is set, it
+   will not have any effect.
 
-   This parameter must be set of the module will not load.
+   This parameter must be set or the module will not load.
 
    Default value is "Not set!".
 
@@ -250,26 +286,26 @@ route {
   ...
 }
 
-1.5. Exported Functions
+5. Exported Functions
+
+   5.1. sstCheckMin(send_reply_flag)
 
-1.5.1.  sstCheckMin(send_reply_flag)
+5.1. sstCheckMin(send_reply_flag)
 
    Check the current Session-Expires / MIN-SE values against the
-   sst_min_se parameter value. If the Session-Expires or MIN_SE
-   header value is less then modules minimum value, this function
-   will return true.
+   sst_min_se parameter value. If the Session-Expires or MIN_SE header
+   value is less than the modules minimum value, this function will return
+   true.
 
-   If the fuction is called with the send_reply_flag set to true
-   (1) and the requested Session-Expires / MIN-SE values are too
-   small, a 422 reply will be sent for you. The 422 will carry a
-   MIN-SE: header with the sst min_se parameter value set.
+   If the fuction is called with the send_reply_flag set to true (1) and
+   the requested Session-Expires / MIN-SE values are too small, a 422
+   reply will be sent for you. The 422 will carry a MIN-SE: header with
+   the sst min_se parameter value set.
 
    Meaning of the parameters is as follows:
-     * min_allowed - The value to compare the MIN_SE header value
-       to.
+     * min_allowed - The value to compare the MIN_SE header value to.
 
    Example 1.7. sstCheckMin usage
-
 ...
 modparam("dialog", "timeout_avp", "$avp(i:4242)")
 modparam("dialog", "dlg_flag", 5)
@@ -282,8 +318,7 @@ modparam("sst", "min_se", 2400) # Must be >= 90
 route {
   if (method=="INVITE") {
         if (sstCheckMin("1")) {
-                xlog("L_ERR", "422 Session Timer Too Small reply sent.\n
-");
+                xlog("L_ERR", "422 Session Timer Too Small reply sent.\n");
                 exit;
         }
         # track the session timers via the dialog module
@@ -297,8 +332,7 @@ route {
 route {
   if (method=="INVITE") {
         if (sstCheckMin("0")) {
-                xlog("L_ERR", "Session Timer Too Small, dropping request
-\n");
+                xlog("L_ERR", "Session Timer Too Small, dropping request\n");
                 exit;
         }
         # track the session timers via the dialog module
@@ -308,12 +342,14 @@ route {
 }
 ...
 
-1.6. Exported Statistics
+6. Exported Statistics
+
+   6.1. expired_sst
 
-1.6.1. expired_sst
+6.1. expired_sst
 
    Number of dialogs which got expired session timer.
 
-1.7. Installation and Running
+7. Installation and Running
 
-   just load the module and remember to set the timeout_avp value.
+   Just load the module and remember to set the timeout_avp value.

modules_k/sst/doc/sst_admin.xml

@@ -15,47 +15,54 @@
 	
 	<section>
 		<title>Overview</title>
+		<para>SIP session timers are used to make sure that
+		a session (dialog) is still alive, even though there
+		may have been a long time since the last in-dialog message.
+		If the other end is not responding, the dialog will
+		be hung up automatically. SIP session timers need to
+		be supported by all end points for it to work. It's a
+		SIP extension, standardized by the IETF.</para>
 
 		<para>The sst module provides a way to update the
-		dialog expire timer based on the SIP INVITE/200 OK
+		dialog expiry timer based on the SIP INVITE/200 OK
 		Session-Expires header value. You can use the sst
-		module in an Kamailio proxy to allow freeing of local
-		resources of dead (expired) calls.</para>
+		module in an &kamailio; proxy to allow freeing of local
+		resources of dead calls.</para>
 
 		<para>You can also use the sst module to validate the
 		MIN_SE header value and reply to any request with a
 		"422 - Session Timer Too Small" if the value is too
-		small for your Kamailio configuration.</para>
+		small for your &kamailio; configuration.</para>
 
 	</section>
 	
 	<section>
 	<title>How it works</title>
 	
-	<para>The sst module uses the dialog module to be notified of
+	<para>The sst module uses the <quote>dialog module</quote> to be notified of
 	any new or updated dialogs. It will then look for and extract
 	the session-expire: header value (if there is one) and
 	override the dialog expire timer value for the current context
 	dialog by setting the avp value.</para>
 
 	<para>You flag any call setup INVITE that you want to cause a
-	timed session to be established. This will cause Kamailio to
-	request the use of session times if the UAC does not request
+	timed session to be established. This will cause &kamailio; to
+	request the use of session timers if the UAC does not request
 	it.</para>
 
 	<para>All of this happens with a properly configured dialog
 	and sst module and setting the dialog flag and the sst flag at
 	the time any INVITE sip message is seen. There is no
-	kamailio.cfg script function call required to set the dialog
-	expire timeout value. See the dialog module users guide for
+	&kamailioconfig; script function call required to set the dialog
+	expire timeout value. See the <quote>dialog module</quote> users guide for
 	more information.</para>
 
-	<para>The sstCheckMin() script function can be used to varify
-	the Session-expires / MIN-SE header field values are not too
-	small for a proxy. If the SST min_se parameter value is
-	smaller then the messages Session-Expires / MIN-SE values, the
+	<para>The <quote>sstCheckMin()</quote> script function can be used to verify
+	that the Session-expires / MIN-SE header field values are not too
+	small for your server. If the SST min_se parameter value is
+	smaller than the messages Session-Expires / MIN-SE values, the
 	test will return true. You can also configure the function to
-	send the 422 response for you.</para>
+	send the 422 error response for you.</para>
 
 	<para>The following was taken from the RFC as a call flow
 	example:</para>
@@ -116,7 +123,7 @@
 		<itemizedlist>
 		<listitem>
 		<para>
-		<emphasis>dialog</emphasis> - dialog module and its decencies. (tm)
+		<emphasis>dialog</emphasis> - dialog module and its dependencies. (tm)
 		</para>
 		</listitem>
 		<listitem>
@@ -172,11 +179,11 @@ modparam("sst", "enable_stats", 0)
 		<title><varname>min_se</varname> (integer)</title>
 
 		<para>The value is used to set the proxies MIN-SE
-		value and is used in the 422 reply as the proxies
-		MIN-SE: header value if the sstCheckMin() flag is set
+		value and is used in the 422 error reply as the proxys
+		MIN-SE: header value if the <quote>sstCheckMin()</quote> flag is set
 		to true and the check fails.</para>
 
-		<para>If not set and sstCheckMin() is called with the
+		<para>If not set and <quote>sstCheckMin()</quote> is called with the
 		send-reply flag set to true, the default 1800 seconds
 		will be used as the compare and the MIN-SE: header
 		value if the 422 reply is sent.</para>
@@ -200,11 +207,11 @@ modparam("sst", "min_se", 2400)
 		<title><varname>timeout_avp</varname> (string)</title>
 
 		<para>This parameter MUST be set to the same value as the
-		dialog parameter of the same name. If this parameter is
+		dialog module parameter of the same name. If this parameter is
 		NOT set, the sst module will not do anything!</para>
 
 		<para>This is how the sst module knows which avp in the
-		dialog module to change with the new expire value.</para>
+		dialog module it has to change with the new expire value.</para>
 
 		<para>
 		<emphasis>
@@ -226,16 +233,16 @@ modparam("sst", "timeout_avp", "$avp(i:10)")
 		<title><varname>reject_to_small</varname> (integer)</title>
 
 		<para>In the initial INVITE if the UAC has requested a
-		Session-Expire: and it's value is smaller then our
+		Session-Expire: and it's value is smaller than our
 		local policies Min-SE (see min_se above), then the
-		PROXY has the right to reject the call by replying to
-		the message with a 422 Session Timer Too Small and
+		proxy has the right to reject the call by replying to
+		the message with a <quote>422 Session Timer Too Small</quote> and
 		state our local Min-SE: value. The INVITE is NOT
-		forwarded on through the PROXY.</para>
+		forwarded on through the proxy.</para>
 
-		<para>This flag if true will tell the SST module to
+		<para>If this flag is true, the SST module to
 		reject the INVITE with a 422 response. If false, the
-		INVITE is forwarded through the PROXY with out any
+		INVITE is forwarded through the PROXY without any
 		modifications.</para>
 
 		<para>
@@ -255,21 +262,21 @@ modparam("sst", "reject_to_small", 0)
 <section>
 		<title><varname>sst_flag</varname> (integer)</title>
 		
-		<para>Keeping with Kamailio, the module will not do
+		<para>Keeping with &kamailio;, the module will not do
 		anything to any message unless instructed to do so via
-		the kamailio.cfg script. You must set the sst_flag
+		the &kamailioconfig; script. You must set the sst_flag
 		value in the setflag() call of the INVITE you want the
 		sst module to process. But before you can do that, you
 		need to tell the sst module which flag value you are
 		assigning to sst.</para>
 
-		<para>In most cases when ever you set the dialog flag
+		<para>In most cases whenever you set the dialog flag
 		you will want to set the sst flag. If the dialog flag
 		is not set and the sst flag is set, it will not have
 		any effect.</para>
 
-		<para>This parameter must be set of the module will
-		not load.</para>
+		<para><emphasis>This parameter must be set or the module will
+		not load.</emphasis></para>
 
 		<para>
 		<emphasis>
@@ -305,7 +312,7 @@ route {
 
 		<para>Check the current Session-Expires / MIN-SE values
 		against the sst_min_se parameter value. If the
-		Session-Expires or MIN_SE header value is less then
+		Session-Expires or MIN_SE header value is less than the
 		modules minimum value, this function will return
 		true. </para>
 
@@ -380,7 +387,7 @@ route {
 
     <section>
 	<title>Installation and Running</title>
-	<para>just load the module and remember to set the timeout_avp value.</para>
+	<para>Just load the module and remember to set the timeout_avp value.</para>
 	</section>
 </chapter>
 

stats.c

@@ -34,7 +34,7 @@
 
 /*!
  * \file
- * \brief SIP-router core :: 
+ * \brief SIP-router core :: Stats reporting code
  * \ingroup core
  * Module: \ref core
  */