timer Small updates to README to adapt to more generic Kamailio structure
authorOlle E. Johansson <oej@edvina.net>
Thu, 5 May 2016 19:08:58 +0000 (21:08 +0200)
committerOlle E. Johansson <oej@edvina.net>
Thu, 5 May 2016 19:08:58 +0000 (21:08 +0200)
modules/timer/README
modules/timer/doc/timer.xml
modules/timer/timer.c

index e6af28c..4fee82f 100644 (file)
@@ -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";
 
index 3b98f55..f815ae2 100644 (file)
 <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>
     <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">
                        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>
                                <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>
index abfbb70..b708f7b 100644 (file)
@@ -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;