00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 2008 - 2009, Digium, Inc. 00005 * 00006 * Kevin P. Fleming <kpfleming@digium.com> 00007 * Russell Bryant <russell@digium.com> 00008 * 00009 * See http://www.asterisk.org for more information about 00010 * the Asterisk project. Please do not directly contact 00011 * any of the maintainers of this project for assistance; 00012 * the project provides a web site, mailing lists and IRC 00013 * channels for your use. 00014 * 00015 * This program is free software, distributed under the terms of 00016 * the GNU General Public License Version 2. See the LICENSE file 00017 * at the top of the source tree. 00018 */ 00019 00020 /*! 00021 \file timing.h 00022 \brief Timing source management 00023 \author Kevin P. Fleming <kpfleming@digium.com> 00024 \author Russell Bryant <russell@digium.com> 00025 00026 Portions of Asterisk require a timing source, a periodic trigger 00027 for media handling activities. The functions in this file allow 00028 a loadable module to provide a timing source for Asterisk and its 00029 modules, so that those modules can request a 'timing handle' when 00030 they require one. These handles are file descriptors, which can be 00031 used with select() or poll(). 00032 00033 The timing source used by Asterisk must provide the following 00034 features: 00035 00036 1) Periodic triggers, with a configurable interval (specified as 00037 number of triggers per second). 00038 00039 2) Multiple outstanding triggers, each of which must be 'acked' 00040 to clear it. Triggers must also be 'ackable' in quantity. 00041 00042 3) Continuous trigger mode, which when enabled causes every call 00043 to poll() on the timer handle to immediately return. 00044 00045 4) Multiple 'event types', so that the code using the timer can 00046 know whether the wakeup it received was due to a periodic trigger 00047 or a continuous trigger. 00048 */ 00049 00050 #ifndef _ASTERISK_TIMING_H 00051 #define _ASTERISK_TIMING_H 00052 00053 #if defined(__cplusplus) || defined(c_plusplus) 00054 extern "C" { 00055 #endif 00056 00057 enum ast_timer_event { 00058 AST_TIMING_EVENT_EXPIRED = 1, 00059 AST_TIMING_EVENT_CONTINUOUS = 2, 00060 }; 00061 00062 /*! 00063 * \brief Timing module interface 00064 * 00065 * The public API calls for the timing API directly map to this interface. 00066 * So, the behavior of these calls should match the documentation of the 00067 * public API calls. 00068 */ 00069 struct ast_timing_interface { 00070 const char *name; 00071 /*! This handles the case where multiple timing modules are loaded. 00072 * The highest priority timing interface available will be used. */ 00073 unsigned int priority; 00074 int (*timer_open)(void); 00075 void (*timer_close)(int handle); 00076 int (*timer_set_rate)(int handle, unsigned int rate); 00077 void (*timer_ack)(int handle, unsigned int quantity); 00078 int (*timer_enable_continuous)(int handle); 00079 int (*timer_disable_continuous)(int handle); 00080 enum ast_timer_event (*timer_get_event)(int handle); 00081 unsigned int (*timer_get_max_rate)(int handle); 00082 }; 00083 00084 /*! 00085 * \brief Register a set of timing functions. 00086 * 00087 * \param i An instance of the \c ast_timing_interfaces structure with pointers 00088 * to the functions provided by the timing implementation. 00089 * 00090 * \retval NULL failure 00091 * \retval non-Null handle to be passed to ast_unregister_timing_interface() on success 00092 * \since 1.6.1 00093 */ 00094 #define ast_register_timing_interface(i) _ast_register_timing_interface(i, ast_module_info->self) 00095 void *_ast_register_timing_interface(struct ast_timing_interface *funcs, 00096 struct ast_module *mod); 00097 00098 /*! 00099 * \brief Unregister a previously registered timing interface. 00100 * 00101 * \param handle The handle returned from a prior successful call to 00102 * ast_register_timing_interface(). 00103 * 00104 * \retval 0 success 00105 * \retval non-zero failure 00106 * \since 1.6.1 00107 */ 00108 int ast_unregister_timing_interface(void *handle); 00109 00110 struct ast_timer; 00111 00112 /*! 00113 * \brief Open a timer 00114 * 00115 * \retval NULL on error, with errno set 00116 * \retval non-NULL timer handle on success 00117 * \since 1.6.1 00118 */ 00119 struct ast_timer *ast_timer_open(void); 00120 00121 /*! 00122 * \brief Close an opened timing handle 00123 * 00124 * \param handle timer handle returned from timer_open() 00125 * 00126 * \return nothing 00127 * \since 1.6.1 00128 */ 00129 void ast_timer_close(struct ast_timer *handle); 00130 00131 /*! 00132 * \brief Get a poll()-able file descriptor for a timer 00133 * 00134 * \param handle timer handle returned from timer_open() 00135 * 00136 * \return file descriptor which can be used with poll() to wait for events 00137 * \since 1.6.1 00138 */ 00139 int ast_timer_fd(const struct ast_timer *handle); 00140 00141 /*! 00142 * \brief Set the timing tick rate 00143 * 00144 * \param handle timer handle returned from timer_open() 00145 * \param rate ticks per second, 0 turns the ticks off if needed 00146 * 00147 * Use this function if you want the timer to show input at a certain 00148 * rate. The other alternative use of a timer is the continuous 00149 * mode. 00150 * 00151 * \retval -1 error, with errno set 00152 * \retval 0 success 00153 * \since 1.6.1 00154 */ 00155 int ast_timer_set_rate(const struct ast_timer *handle, unsigned int rate); 00156 00157 /*! 00158 * \brief Acknowledge a timer event 00159 * 00160 * \param handle timer handle returned from timer_open() 00161 * \param quantity number of timer events to acknowledge 00162 * 00163 * \note This function should only be called if timer_get_event() 00164 * returned AST_TIMING_EVENT_EXPIRED. 00165 * 00166 * \return nothing 00167 * \since 1.6.1 00168 */ 00169 void ast_timer_ack(const struct ast_timer *handle, unsigned int quantity); 00170 00171 /*! 00172 * \brief Enable continuous mode 00173 * 00174 * \param handle timer handle returned from timer_open() 00175 * 00176 * Continuous mode causes poll() on the timer's fd to immediately return 00177 * always until continuous mode is disabled. 00178 * 00179 * \retval -1 failure, with errno set 00180 * \retval 0 success 00181 * \since 1.6.1 00182 */ 00183 int ast_timer_enable_continuous(const struct ast_timer *handle); 00184 00185 /*! 00186 * \brief Disable continuous mode 00187 * 00188 * \param handle timer handle returned from timer_close() 00189 * 00190 * \retval -1 failure, with errno set 00191 * \retval 0 success 00192 * \since 1.6.1 00193 */ 00194 int ast_timer_disable_continuous(const struct ast_timer *handle); 00195 00196 /*! 00197 * \brief Retrieve timing event 00198 * 00199 * \param handle timer handle returned by timer_open() 00200 * 00201 * After poll() indicates that there is input on the timer's fd, this will 00202 * be called to find out what triggered it. 00203 * 00204 * \return which event triggered the timer 00205 * \since 1.6.1 00206 */ 00207 enum ast_timer_event ast_timer_get_event(const struct ast_timer *handle); 00208 00209 /*! 00210 * \brief Get maximum rate supported for a timer 00211 * 00212 * \param handle timer handle returned by timer_open() 00213 * 00214 * \return maximum rate supported by timer 00215 * \since 1.6.1 00216 */ 00217 unsigned int ast_timer_get_max_rate(const struct ast_timer *handle); 00218 00219 /*! 00220 * \brief Get name of timer in use 00221 * 00222 * \param handle timer handle returned by timer_open() 00223 * 00224 * \return name of timer 00225 * \since 1.6.2 00226 */ 00227 const char *ast_timer_get_name(const struct ast_timer *handle); 00228 00229 #if defined(__cplusplus) || defined(c_plusplus) 00230 } 00231 #endif 00232 00233 #endif /* _ASTERISK_TIMING_H */