timer module

Tomas Mandys

   Iptel.org
   <tomas dot mandys at iptel dot org>

   Copyright © 2007 iptelorg GmbH
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. ABNF syntax
        4. Parameters

              4.1. declare_timer (string)

        5. Functions

              5.1. timer_enable(timer_id, enable_disable)

        6. Selects

              6.1. @timer.timer.timer_id.enabled
              6.2. @timer.executed

        7. Examples

   List of Examples

   1.1. Example declare_timer
   1.2. timer_enable usage
   1.3. timer.timer.timer_id.enabled usage
   1.4. timer.executed usage
   1.5. Common example using timer module
   1.6. Using timer module with kemi
   1.7. Using timer module for testing a functionality

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. ABNF syntax
   4. Parameters

        4.1. declare_timer (string)

   5. Functions

        5.1. timer_enable(timer_id, enable_disable)

   6. Selects

        6.1. @timer.timer.timer_id.enabled
        6.2. @timer.executed

   7. Examples

1. Overview

   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

   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

...
        timer_id = alphanum
        slow_fast = "slow" | "fast"
        declare_timer_syntax = timer_id "=" (route#|route_name) "," interval ","
 slow_fast "," ["enable"]
        enable_disable = "0" | "1"
...

4. Parameters

   4.1. declare_timer (string)

4.1. declare_timer (string)

   Declares timer route which will be called in specific interval.

   The format is:
                        declare_timer = declare_timer_syntax

     * timer_id is timer identifier.
     * route is handler to be called when timer is triggered. It has to be
       a route block name when native scripting is used, or Kemi function
       name. The Kemi function name receives one string parameter (for now
       it has a static value, respectively the module name).
     * 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
...
modparam("timer", "declare_timer", "MY_TIMER=MY_TIMER_ROUTE,10,slow,enable");
...

5. Functions

   5.1. timer_enable(timer_id, enable_disable)

5.1.  timer_enable(timer_id, enable_disable)

   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.
     * enable_disable - set to 1 to enable timer, to 0 to disable.

   Example 1.2. timer_enable usage
...
timer_enable("MY_TIMER", 1);
...

6. Selects

   6.1. @timer.timer.timer_id.enabled
   6.2. @timer.executed

6.1.  @timer.timer.timer_id.enabled

   Return true ("1") if timer specified by timer_id is enabled, otherwise
   returns false ("0").

   Example 1.3. timer.timer.timer_id.enabled usage
...
if (@timer.timer.MY_TIMER.enabled == "1") {
        ...
}
...

6.2.  @timer.executed

   Returns name of timer which has been executed, i.e. non empty value is
   returned only when handler is being processed.

   Example 1.4. timer.executed usage
...
if (@timer.executed != "") {
        # timer is being handled
        ...
}
...

7. Examples

   Example 1.5. Common example using timer module
...
loadmodule "xlog.so"
loadmodule "timer.so"

modparam("timer", "declare_timer", "tmr1=ONTIMER,1000");
modparam("timer", "declare_timer", "tmr2=ONTIMER2,2000,slow,enable");

route["print"] {
        xlog("fired: $sel(@timer.executed)\n");
}

route["ONTIMER"] {
        # do something
        route("print");}


route["ONTIMER2"] {
        # do something
        timer_enable("tmr1", 0);
        route("print");
}
...

   Example 1.6. Using timer module with kemi
...
loadmodule "timer.so"

modparam("timer", "declare_timer", "tmr1=ksr_timer,1000");
...

...
-- timer event callback function implemented in Lua
function ksr_timer(evname)
        KSR.info("===== timer module triggered event\n");
        return 1;
end
...

   Example 1.7. 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.
...
loadmodule "timer";
loadmodule "xlog";

modparam("timer", "declare_timer", "TIMER_TEST=TEST,100,,enable");

request_route {
        xlog("main route");
}

route[TEST] {
        timer_enable("TIMER_TEST", "0");
        xlog("test start\n");

        # add here tested functionality

        xlog("test end\n");
}
...
