426eb8dbd242935c0df0d2684e87a8505bfc7bd5
[asterisk/asterisk.git] / include / asterisk / timing.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2008, Digium, Inc.
5  *
6  * Kevin P. Fleming <kpfleming@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*!
20   \file timing.h
21   \brief Timing source management
22   \author Kevin P. Fleming <kpfleming@digium.com>
23
24   Portions of Asterisk require a timing source, a periodic trigger
25   for media handling activities. The functions in this file allow
26   a loadable module to provide a timing source for Asterisk and its
27   modules, so that those modules can request a 'timing handle' when
28   they require one. These handles are file descriptors, which can be
29   used with select() or poll().
30
31   The timing source used by Asterisk must provide the following
32   features:
33
34   1) Periodic triggers, with a configurable interval (specified in
35      millisconds).
36
37   2) Multiple outstanding triggers, each of which must be 'acked'
38      to clear it. Triggers must also be 'ackable' in quantity.
39
40   3) Continuous trigger mode, which when enabled causes every call
41      to poll() on the timer handle to immediately return.
42
43   4) Multiple 'event types', so that the code using the timer can
44      know whether the wakeup it received was due to a periodic trigger
45      or a continuous trigger.
46  */
47
48 #ifndef _ASTERISK_TIMING_H
49 #define _ASTERISK_TIMING_H
50
51 #if defined(__cplusplus) || defined(c_plusplus)
52 extern "C" {
53 #endif
54
55 enum ast_timing_event {
56         AST_TIMING_EVENT_EXPIRED = 1,
57         AST_TIMING_EVENT_CONTINUOUS = 2,
58 };
59
60 struct ast_timing_functions {
61         int (*timer_open)(unsigned int rate);
62         void (*timer_close)(int handle);
63         void (*timer_ack)(int handle, unsigned int quantity);
64         int (*timer_enable_continuous)(int handle);
65         int (*timer_disable_continuous)(int handle);
66         enum ast_timing_event (*timer_get_event)(int handle);
67 };
68
69 /*!
70   \brief Install a set of timing functions.
71   \param funcs An instance of the \c ast_timing_functions structure with pointers
72   to the functions provided by the timing implementation.
73   \retval NULL on failure, or a handle to be passed to
74   ast_uninstall_timing_functions() on success
75  */
76 void *ast_install_timing_functions(struct ast_timing_functions *funcs);
77
78 /*!
79   \brief Uninstall a previously-installed set of timing functions.
80   \param handle The handle returned from a prior successful call to
81   ast_install_timing_functions().
82   \retval none
83  */
84 void ast_uninstall_timing_functions(void *handle);
85
86 /*!
87   \brief Open a timer handle.
88   \param rate The rate at which the timer should trigger.
89   \retval -1 on failure, or a positive integer on success
90  */
91 int ast_timer_open(unsigned int rate);
92
93 /*!
94   \brief Close a previously-opened timer handle.
95   \param handle The timer handle to close.
96   \retval none
97  */
98 void ast_timer_close(int handle);
99
100 void ast_timer_ack(int handle, unsigned int quantity);
101
102 int ast_timer_enable_continuous(int handle);
103
104 int ast_timer_disable_continous(int handle);
105
106 enum ast_timing_event ast_timer_get_event(int handle);
107
108 #if defined(__cplusplus) || defined(c_plusplus)
109 }
110 #endif
111
112 #endif /* _ASTERISK_TIMING_H */