timer Small updates to README to adapt to more generic Kamailio structure

modules/timer/README

@@ -3,6 +3,7 @@ timer module
 Tomas Mandys
 
    Iptel.org
+   <tomas dot mandys at iptel dot org>
 
    Copyright © 2007 iptelorg GmbH
      __________________________________________________________________
@@ -13,6 +14,10 @@ Tomas Mandys
 
         1. Overview
         2. Dependencies
+
+              2.1. Kamailio Modules
+              2.2. External Libraries or Applications
+
         3. ABNF syntax
         4. Parameters
 
@@ -41,6 +46,10 @@ Chapter 1. Admin Guide
 
    1. Overview
    2. Dependencies
+
+        2.1. Kamailio Modules
+        2.2. External Libraries or Applications
+
    3. ABNF syntax
    4. Parameters
 
@@ -56,11 +65,25 @@ Chapter 1. Admin Guide
 
 1. Overview
 
-   The module supports triggering specific route block on timer.
+   The module supports triggering a specific route block on a specific
+   timer. The timer can be activated and de-activated from the routing
+   script at runtime.
 
 2. Dependencies
 
-   none
+   2.1. Kamailio Modules
+   2.2. External Libraries or Applications
+
+2.1. Kamailio Modules
+
+   The following modules must be loaded before this module:
+     * none
+
+2.2. External Libraries or Applications
+
+   The following libraries or applications must be installed before
+   running Kamailio with this module loaded:
+     * none.
 
 3. ABNF syntax
 
@@ -81,13 +104,15 @@ Chapter 1. Admin Guide
    The format is:
                         declare_timer = declare_timer_syntax
 
-   timer_id is timer identifier, route is handler to be called when timer
-   is triggered, interval is timer interval in milliseconds, slow_fast
-   determines if handler will be hooked in slow or fast timer queue, fast
-   timer handler returns as quickly as possible, slow timer handler may
-   spend longer time, see kamailio/doc/timers.txt documentation. Use
-   enable to enable timer when Kamailio is starting, otherwise use
-   timer_enable to start it later.
+     * timer_id is timer identifier,
+     * route is handler to be called when timer is triggered,
+     * interval is timer interval in milliseconds,
+     * slow_fast determines if handler will be hooked in slow or fast
+       timer queue, fast timer handler returns as quickly as possible,
+       slow timer handler may spend longer time, see
+       kamailio/doc/timers.txt documentation.
+     * enable - enable timer when Kamailio is starting, otherwise use
+       timer_enable to start it later.
 
    Example 1.1. Example declare_timer
         ...
@@ -106,8 +131,9 @@ le");
    Enable/disable timer route specified by timer_id. Because of timer core
    API the callback is not disabled immediately but is removed from
    handler by itself not to decrease performance. Disabling and enabling
-   in sequence may be tricky. timer_id references to timer declared by
-   declare_timer.
+   in sequence may be tricky.
+     * timer_id references to timer declared by declare_timer.
+     * enable_distable - set to 1 to enable timer, to 0 to disable.
 
    Example 1.2. timer_enable usage
         ...
@@ -162,8 +188,8 @@ route["ONTIMER2"] {
    Example 1.6. Using timer module for testing a functionality
 
    The timer module may be used to test a functionality being developed
-   and not requiring real request.A developer may put tested code in route
-   section which is called once after Kamailio starts.
+   and not requiring real request. A developer may put tested code in
+   route section which is called once after Kamailio starts.
 loadmodule "timer";
 loadmodule "xprint";
 

modules/timer/doc/timer.xml

@@ -11,14 +11,13 @@
 <book id="timer" xmlns:xi="http://www.w3.org/2001/XInclude">
     <bookinfo>
         <title>timer module</title>
+	<productname class="trade">&kamailioname;</productname>
 	<authorgroup>
 	    <author>
 		<firstname>Tomas</firstname>
 		<surname>Mandys</surname>
 		<affiliation><orgname>Iptel.org</orgname></affiliation>
-		<address>
-		    <email>tomas dot mandys at iptel dot org</email>
-		</address>
+	        <email>tomas dot mandys at iptel dot org</email>
 	    </author>
 	</authorgroup>
 	<copyright>
@@ -34,16 +33,42 @@
     <section id="timer.overview">
 		<title>Overview</title>
 		<para>
-		The module supports triggering specific route block on timer.
+		The module supports triggering a specific route block on a specific timer.
+		The timer can be activated and de-activated from the routing script at runtime.
+
 		</para>
     </section>
 
 	<section id="timer.dep">
-		<title>Dependencies</title>
-				   
+	   <title>Dependencies</title>
+	   <section>
+		<title>&kamailio; Modules</title>
 		<para>
-		none
+		The following modules must be loaded before this module:
+			<itemizedlist>
+			<listitem>
+			<para>
+			none
+			</para>
+			</listitem>
+			</itemizedlist>
+		</para>
+	   </section>
+	   <section>
+		<title>External Libraries or Applications</title>
+		<para>
+		The following libraries or applications must be
+		installed before  
+		running &kamailio; with this module loaded:
+			<itemizedlist>
+			<listitem>
+			<para>
+				<emphasis>none</emphasis>.
+			</para>
+			</listitem>
+			</itemizedlist>
 		</para>
+	   </section>
 	</section>
 
 	<section id="timer.syntax">
@@ -73,11 +98,28 @@
 			declare_timer = declare_timer_syntax
 			</programlisting>
 			<para>
-			<emphasis>timer_id</emphasis> is timer identifier, <emphasis>route</emphasis> is handler to be called when
-			timer is triggered, <emphasis>interval</emphasis> is timer interval in milliseconds, <emphasis>slow_fast</emphasis>
-			determines if handler will be hooked in slow or fast timer queue, fast timer handler returns
-			as quickly as possible, slow timer handler may spend longer time, see kamailio/doc/timers.txt documentation. Use <emphasis>enable</emphasis>
-			to enable timer when &kamailio; is starting, otherwise use <function>timer_enable</function> to start it later.		
+				<itemizedlist>
+				<listitem>
+				<emphasis>timer_id</emphasis> is timer identifier,
+				</listitem>
+				<listitem>
+				<emphasis>route</emphasis> is handler to be called when
+				timer is triggered,
+				</listitem>
+				<listitem>
+				<emphasis>interval</emphasis> is timer interval in milliseconds,
+				</listitem>
+				<listitem>
+				<emphasis>slow_fast</emphasis> determines if handler will be
+				hooked in slow or fast timer queue, fast timer handler returns
+				as quickly as possible, slow timer handler may spend longer time,
+				see kamailio/doc/timers.txt documentation. 
+				</listitem>
+				<listitem>
+				<emphasis>enable</emphasis> - enable timer when &kamailio; is starting,
+				otherwise use <function>timer_enable</function> to start it later.		
+				</listitem>
+				</itemizedlist>
 			</para>
 			<example>
 				<title>Example <varname>declare_timer</varname></title>
@@ -99,11 +141,21 @@
 				<function>timer_enable(timer_id, enable_disable)</function>
 			</title>
 			<para>
-				Enable/disable timer route specified by <varname>timer_id</varname>. Because of timer core API the callback
-				is not disabled immediately but is removed from handler by itself not to decrease performance.
+				Enable/disable timer route specified by <varname>timer_id</varname>.
+				Because of timer core API the callback
+				is not disabled immediately but is removed from handler by
+				itself not to decrease performance.
 				Disabling and enabling in sequence may be tricky.
-								  
-				<emphasis>timer_id</emphasis> references to timer declared by <varname>declare_timer</varname>.
+				<itemizedlist>
+				<listitem>
+				<emphasis>timer_id</emphasis> references to timer declared by 
+				<varname>declare_timer</varname>.
+				</listitem>
+				<listitem>
+				<emphasis>enable_distable</emphasis> - set to 1 to enable timer,
+				to 0 to disable.
+				</listitem>
+				</itemizedlist>
 			</para>
 
 			<example>
@@ -193,7 +245,7 @@ route["ONTIMER2"] {
 			<title>Using timer module for testing a functionality</title>
 			<para>
 				The timer module may be used to test a functionality being developed and 
-				not requiring real request.A developer may put tested code in route section
+				not requiring real request. A developer may put tested code in route section
 				which is called once after &kamailio; starts.
 			</para>
 			<programlisting>

modules/timer/timer.c

@@ -110,14 +110,16 @@ static int sel_timer(str* res, select_t* s, struct sip_msg* msg) {
 
 static int sel_enabled(str* res, select_t* s, struct sip_msg* msg) {
 	static char buf[2] = "01";
-	if (!msg) return sel_timer(res, s, msg);
+	if (!msg)
+		return sel_timer(res, s, msg);
 	res->len = 1;
 	res->s = &buf[(((struct timer_action*) s->params[2].v.p)->link->flags & F_TIMER_ACTIVE) != 0];
 	return 0;
 }
 
 static int sel_executed(str* res, select_t* s, struct sip_msg* msg) {
-	if (!timer_executed) return 1;
+	if (!timer_executed)
+		return 1;
 	res->s = timer_executed->timer_name;
 	res->len = strlen(res->s);
 	return 0;
@@ -204,8 +206,7 @@ static ticks_t timer_handler(ticks_t ticks, struct timer_ln* tl, void* data) {
 	        /* end critical section */
 		return 0;   /* do no call more */
 	}
-	else
-        	return (ticks_t)(-1); /* periodical */
+        return (ticks_t)(-1); /* periodical */
 }
 
 static int timer_enable_fixup(void** param, int param_no) {
@@ -291,7 +292,8 @@ static int declare_timer(modparam_t type, char* param) {
 	timer_name = 0;
 	save_p = p = param;
 	eat_alphanum(p);
-	if (*p != '=' || p == save_p) goto err;
+	if (*p != '=' || p == save_p)
+		goto err;
 	*p = '\0';
 	timer_name = save_p;
 	p++;
@@ -311,8 +313,10 @@ static int declare_timer(modparam_t type, char* param) {
 	route_no = n;
 
 	save_p = p;
-	if (!get_next_part(&p, &s, ',')) goto err;
-	if (str2int(&s, &interval) < 0) goto err;
+	if (!get_next_part(&p, &s, ','))
+		goto err;
+	if (str2int(&s, &interval) < 0)
+		goto err;
 
 	save_p = p;
 	flags = 0;