name mode size
..
doc 040000
Makefile 100644 228B
README 100644 5.78kB
timer.c 100644 12.22kB
README
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 "modules/xprint/xprint.so" loadmodule "modules/timer/timer.so" modparam("timer", "declare_timer", "tmr1=ONTIMER,1000"); modparam("timer", "declare_timer", "tmr2=ONTIMER2,2000,slow,enable"); route["print"] { xplog("L_INFO", "fired: %@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 "xprint"; modparam("timer", "declare_timer", "TIMER_TEST=TEST,100,,enable"); request_route { xplog("L_E","main route"); } route[TEST] { timer_enable("TIMER_TEST", "0"); xplog("L_E","test start\n"); # add here tested functionality xplog("L_E","test end\n"); } ...