timer module

Tomas Mandys

Iptel.org

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

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

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)

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)

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

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");
	}
...