Wed Aug 7 17:15:46 2019

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    int (*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  * \retval -1 failure, with errno set
00167  * \retval 0 success
00168  * \since 10.5.2
00169  */
00170 int ast_timer_ack(const struct ast_timer *handle, unsigned int quantity);
00171 
00172 /*!
00173  * \brief Enable continuous mode
00174  *
00175  * \param handle timer handle returned from timer_open()
00176  *
00177  * Continuous mode causes poll() on the timer's fd to immediately return
00178  * always until continuous mode is disabled.
00179  *
00180  * \retval -1 failure, with errno set
00181  * \retval 0 success
00182  * \since 1.6.1
00183  */
00184 int ast_timer_enable_continuous(const struct ast_timer *handle);
00185 
00186 /*!
00187  * \brief Disable continuous mode
00188  *
00189  * \param handle timer handle returned from timer_close()
00190  *
00191  * \retval -1 failure, with errno set
00192  * \retval 0 success
00193  * \since 1.6.1
00194  */
00195 int ast_timer_disable_continuous(const struct ast_timer *handle);
00196 
00197 /*!
00198  * \brief Retrieve timing event
00199  *
00200  * \param handle timer handle returned by timer_open()
00201  *
00202  * After poll() indicates that there is input on the timer's fd, this will
00203  * be called to find out what triggered it.
00204  *
00205  * \return which event triggered the timer
00206  * \since 1.6.1
00207  */
00208 enum ast_timer_event ast_timer_get_event(const struct ast_timer *handle);
00209 
00210 /*!
00211  * \brief Get maximum rate supported for a timer
00212  *
00213  * \param handle timer handle returned by timer_open()
00214  *
00215  * \return maximum rate supported by timer
00216  * \since 1.6.1
00217  */
00218 unsigned int ast_timer_get_max_rate(const struct ast_timer *handle);
00219 
00220 /*!
00221  * \brief Get name of timer in use
00222  *
00223  * \param handle timer handle returned by timer_open()
00224  *
00225  * \return name of timer
00226  * \since 1.6.2
00227  */
00228 const char *ast_timer_get_name(const struct ast_timer *handle);
00229 
00230 #if defined(__cplusplus) || defined(c_plusplus)
00231 }
00232 #endif
00233 
00234 #endif /* _ASTERISK_TIMING_H */

Generated on 7 Aug 2019 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1