- add get_max_rate timing API call
[asterisk/asterisk.git] / include / asterisk / timing.h
index 426eb8d..88f1fc1 100644 (file)
@@ -31,8 +31,8 @@
   The timing source used by Asterisk must provide the following
   features:
 
   The timing source used by Asterisk must provide the following
   features:
 
-  1) Periodic triggers, with a configurable interval (specified in
-     millisconds).
+  1) Periodic triggers, with a configurable interval (specified as
+     number of triggers per second).
 
   2) Multiple outstanding triggers, each of which must be 'acked'
      to clear it. Triggers must also be 'ackable' in quantity.
 
   2) Multiple outstanding triggers, each of which must be 'acked'
      to clear it. Triggers must also be 'ackable' in quantity.
@@ -57,54 +57,134 @@ enum ast_timing_event {
        AST_TIMING_EVENT_CONTINUOUS = 2,
 };
 
        AST_TIMING_EVENT_CONTINUOUS = 2,
 };
 
+/*!
+ * \brief Timing module interface
+ *
+ * The public API calls for the timing API directly map to this interface.
+ * So, the behavior of these calls should match the documentation of the
+ * public API calls.
+ */
 struct ast_timing_functions {
 struct ast_timing_functions {
-       int (*timer_open)(unsigned int rate);
+       int (*timer_open)(void);
        void (*timer_close)(int handle);
        void (*timer_close)(int handle);
+       int (*timer_set_rate)(int handle, unsigned int rate);
        void (*timer_ack)(int handle, unsigned int quantity);
        int (*timer_enable_continuous)(int handle);
        int (*timer_disable_continuous)(int handle);
        enum ast_timing_event (*timer_get_event)(int handle);
        void (*timer_ack)(int handle, unsigned int quantity);
        int (*timer_enable_continuous)(int handle);
        int (*timer_disable_continuous)(int handle);
        enum ast_timing_event (*timer_get_event)(int handle);
+       unsigned int (*timer_get_max_rate)(int handle);
 };
 
 /*!
 };
 
 /*!
-  \brief Install a set of timing functions.
-  \param funcs An instance of the \c ast_timing_functions structure with pointers
-  to the functions provided by the timing implementation.
-  \retval NULL on failure, or a handle to be passed to
-  ast_uninstall_timing_functions() on success
+ * \brief Install a set of timing functions.
+ *
+ * \param funcs An instance of the \c ast_timing_functions structure with pointers
+ *        to the functions provided by the timing implementation.
+ *
+ * \retval NULL failure 
+ * \retval non-Null handle to be passed to ast_uninstall_timing_functions() on success
  */
 void *ast_install_timing_functions(struct ast_timing_functions *funcs);
 
 /*!
  */
 void *ast_install_timing_functions(struct ast_timing_functions *funcs);
 
 /*!
-  \brief Uninstall a previously-installed set of timing functions.
-  \param handle The handle returned from a prior successful call to
-  ast_install_timing_functions().
-  \retval none
+ * \brief Uninstall a previously-installed set of timing functions.
+ *
+ * \param handle The handle returned from a prior successful call to
+ *        ast_install_timing_functions().
+ *
+ * \return nothing
  */
 void ast_uninstall_timing_functions(void *handle);
 
 /*!
  */
 void ast_uninstall_timing_functions(void *handle);
 
 /*!
-  \brief Open a timer handle.
-  \param rate The rate at which the timer should trigger.
-  \retval -1 on failure, or a positive integer on success
+ * \brief Open a timing fd
+ *
+ * \retval -1 error, with errno set
+ * \retval >=0 success
  */
  */
-int ast_timer_open(unsigned int rate);
+int ast_timer_open(void);
 
 /*!
 
 /*!
-  \brief Close a previously-opened timer handle.
-  \param handle The timer handle to close.
-  \retval none
+ * \brief Close an opened timing handle
+ *
+ * \arg handle timing fd returned from timer_open()
+ *
+ * \return nothing
  */
 void ast_timer_close(int handle);
 
  */
 void ast_timer_close(int handle);
 
+/*!
+ * \brief Set the timing tick rate
+ *
+ * \arg handle timing fd returned from timer_open()
+ * \arg rate ticks per second, 0 turns the ticks off if needed
+ *
+ * Use this function if you want the timing fd to show input at a certain
+ * rate.  The other alternative use of a timing fd, is using the continuous
+ * mode.
+ *
+ * \retval -1 error, with errno set
+ * \retval 0 success
+ */
+int ast_timer_set_rate(int handle, unsigned int rate);
+
+/*!
+ * \brief Acknowledge a timer event
+ *
+ * \arg handle timing fd returned from timer_open()
+ * \arg quantity number of timer events to acknowledge
+ *
+ * \note This function should only be called if timer_get_event()
+ *       returned AST_TIMING_EVENT_EXPIRED.
+ *
+ * \return nothing
+ */
 void ast_timer_ack(int handle, unsigned int quantity);
 
 void ast_timer_ack(int handle, unsigned int quantity);
 
+/*!
+ * \brief Enable continuous mode
+ *
+ * \arg handle timing fd returned from timer_open()
+ *
+ * Continuous mode causes poll() on the timing fd to immediately return
+ * always until continuous mode is disabled.
+ *
+ * \retval -1 failure, with errno set
+ * \retval 0 success
+ */
 int ast_timer_enable_continuous(int handle);
 
 int ast_timer_enable_continuous(int handle);
 
-int ast_timer_disable_continous(int handle);
+/*!
+ * \brief Disable continuous mode
+ *
+ * \arg handle timing fd returned from timer_close()
+ *
+ * \retval -1 failure, with errno set
+ * \retval 0 success
+ */
+int ast_timer_disable_continuous(int handle);
 
 
+/*!
+ * \brief Determine timing event
+ *
+ * \arg handle timing fd returned by timer_open()
+ *
+ * After poll() indicates that there is input on the timing fd, this will
+ * be called to find out what triggered it.
+ *
+ * \return which event triggered the timing fd
+ */
 enum ast_timing_event ast_timer_get_event(int handle);
 
 enum ast_timing_event ast_timer_get_event(int handle);
 
+/*!
+ * \brief Get maximum rate supported for a timing handle
+ *
+ * \arg handle timing fd returned by timer_open()
+ *
+ * \return maximum rate supported for timing handle
+ */
+unsigned int ast_timer_get_max_rate(int handle);
+
 #if defined(__cplusplus) || defined(c_plusplus)
 }
 #endif
 #if defined(__cplusplus) || defined(c_plusplus)
 }
 #endif