# Admin Guide

## 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.

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- none

### External Libraries or Applications

The following libraries or applications must be installed before running &kamailio; with this module loaded:

- none.

## 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"
    ...

## Parameters

### `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 `declare_timer`

    ...
    modparam("timer", "declare_timer", "MY_TIMER=MY_TIMER_ROUTE,10,slow,enable");
    ...

## Functions

### `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.

#### `timer_enable` usage

    ...
    timer_enable("MY_TIMER", 1);
    ...

## Selects

### `@timer.timer.timer_id.enabled`

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

#### `timer.timer.timer_id.enabled` usage

    ...
    if (@timer.timer.MY_TIMER.enabled == "1") {
    	...
    }
    ...

### `@timer.executed`

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

#### `timer.executed` usage

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

## Examples

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

### 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
    ...

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