Mon Jun 27 16:50:57 2011

Asterisk developer's documentation


timing.h

Go to the documentation of this file.
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 */

Generated on Mon Jun 27 16:50:57 2011 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7