kamailio/modules/timer/doc/timer.xml

<?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 "../../../docbook/entities.xml">
%docentities;

]>

<book id="timer" xmlns:xi="http://www.w3.org/2001/XInclude">
    <bookinfo>
        <title>timer module</title>
	<authorgroup>
	    <author>
		<firstname>Tomas</firstname>
		<surname>Mandys</surname>
		<affiliation><orgname>Iptel.org</orgname></affiliation>
		<address>
		    <email>tomas dot mandys at iptel dot org</email>
		</address>
	    </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 specific route block on timer.
		</para>
    </section>

	<section id="timer.dep">
		<title>Dependencies</title>
				   
		<para>
		none
		</para>
	</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>
			<emphasis>timer_id</emphasis> is timer identifier, <emphasis>route</emphasis> is handler to be called when
			timer is triggered, <emphasis>interval</emphasis> is timer interval in milliseconds, <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. Use <emphasis>enable</emphasis>
			to enable timer when &kamailio; is starting, otherwise use <function>timer_enable</function> to start it later.		
			</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.
								  
				<emphasis>timer_id</emphasis> references to timer declared by <varname>declare_timer</varname>.
			</para>

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

		<section id="timer.timer.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.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>timer common example</title>
			<programlisting>
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");
}

			</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 "xprint";  

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

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

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