<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
%docentities;

]>

<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>
	        <email>tomas dot mandys at iptel dot org</email>
	    </author>
	</authorgroup>
	<copyright>
	    <year>2007</year>
	    <holder>iptelorg GmbH</holder>
	</copyright>

    </bookinfo>
    <toc></toc>

    <chapter>
	<title>Admin Guide</title>
    <section id="timer.overview">
		<title>Overview</title>
		<para>
		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>
	   <section>
		<title>&kamailio; Modules</title>
		<para>
		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">
		<title>ABNF syntax</title>
		<programlisting>
...
	timer_id = alphanum
	slow_fast = "slow" | "fast"
	declare_timer_syntax = timer_id "=" (route#|route_name) "," interval "," slow_fast "," ["enable"]
	enable_disable = "0" | "1"
...
		</programlisting>
	</section>

	<section id="timer.parameters">

		<title>Parameters</title>

		<section id="timer.p.declare_timer">
			<title><varname>declare_timer</varname> (string)</title>
			<para>
			Declares timer route which will be called in specific interval.
			</para>
			<para>
			The format is:
			</para>
			<programlisting>
			declare_timer = declare_timer_syntax
			</programlisting>
			<para>
				<itemizedlist>
				<listitem>
				<emphasis>timer_id</emphasis> is timer identifier.
				</listitem>
				<listitem>
				<emphasis>route</emphasis> 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).
				</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>
				<programlisting>
...
modparam("timer", "declare_timer", "MY_TIMER=MY_TIMER_ROUTE,10,slow,enable");
...
				</programlisting>
			</example>
		</section>

	</section>

	<section id="timer.functions">
		<title>Functions</title>

		<section id="timer.p.timer_enable">
			<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.
				Disabling and enabling in sequence may be tricky.
				<itemizedlist>
				<listitem>
				<emphasis>timer_id</emphasis> references to timer declared by
				<varname>declare_timer</varname>.
				</listitem>
				<listitem>
				<emphasis>enable_disable</emphasis> - set to 1 to enable timer,
				to 0 to disable.
				</listitem>
				</itemizedlist>
			</para>

			<example>
				<title><function>timer_enable</function> usage</title>
				<programlisting>
...
timer_enable("MY_TIMER", 1);
...
				</programlisting>
			</example>
		</section>
	</section>

	<section id="timer.selects">
		<title>Selects</title>
		<section id="timer.sel.timer_id.enabled">
			<title>
				<function>@timer.timer.timer_id.enabled</function>
			</title>
			<para>
				Return true ("1") if timer specified by <varname>timer_id</varname> is enabled,
				otherwise returns false ("0").
			</para>

			<example>
				<title><function>timer.timer.timer_id.enabled</function> usage</title>
				<programlisting>
...
if (@timer.timer.MY_TIMER.enabled == "1") {
	...
}
...
				</programlisting>
			</example>
		</section>

		<section id="timer.sel.executed">
			<title>
				<function>@timer.executed</function>
			</title>
			<para>
				Returns name of timer which has been executed, i.e. non empty value is returned only
				when handler is being processed.
			</para>

			<example>
				<title><function>timer.executed</function> usage</title>
				<programlisting>
...
if (@timer.executed != "") {
	# timer is being handled
	...
}
...
				</programlisting>
			</example>
		</section>
	</section>

    <section id="timer.examples">
		<title>Examples</title>
		<example>
			<title>Common example using timer module</title>
			<programlisting>
...
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");
}
...
			</programlisting>
		</example>

		<example>
			<title>Using timer module with kemi</title>
			<programlisting>
...
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
...
			</programlisting>
		</example>
		<example>
			<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
				which is called once after &kamailio; starts.
			</para>
			<programlisting>
...
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");
}
...
			</programlisting>

		</example>
	</section>
    </chapter>
</book>
