Merge a set of device state improvements from team/russell/events.

The way a device state change propagates is kind of silly, in my opinion.  A
device state provider calls a function that indicates that the state of a
device has changed.  Then, another thread goes back and calls a callback for
the device state provider to find out what the new state is before it can go
send it off to whoever cares.

I have changed it so that you can include the state that the device has changed
to in the first function call from the device state provider.  This removes the
need to have to call the callback, which locks up critical containers to go find
out what the state changed to.

This change set changes the "simple" device state providers to use the new method.
This includes parking, meetme, and SLA.

I have also mostly converted chan_agent in my branch, but still have some more
things to think through before presenting the plan for converting channel drivers
to ensure all of the right events get generated ...


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@79027 65c4cc65-6c06-0410-ace0-fbb531ad65f3

1 files changed, 81 insertions, 19 deletions

diff --git a/include/asterisk/devicestate.h b/include/asterisk/devicestate.h
index 08c547649..8ef0b24f6 100644
--- a/include/asterisk/devicestate.h
+++ b/include/asterisk/devicestate.h
@@ -58,73 +58,133 @@ enum ast_device_state {
 	AST_DEVICE_ONHOLD,       /*!< Device is on hold */
 };
 
-/*!  \brief Devicestate provider call back */
+/*! \brief Devicestate provider call back */
 typedef enum ast_device_state (*ast_devstate_prov_cb_type)(const char *data);
 
-/*! \brief Convert device state to text string for output 
+/*! 
+ * \brief Convert device state to text string for output 
+ *
  * \param devstate Current device state 
  */
 const char *devstate2str(enum ast_device_state devstate);
 
-/*! \brief Convert device state to text string that is easier to parse 
+/*! 
+ * \brief Convert device state to text string that is easier to parse 
+ *
  * \param devstate Current device state 
  */
 const char *ast_devstate_str(enum ast_device_state devstate);
 
-/*! \brief Convert device state from text to integer value
+/*! 
+ * \brief Convert device state from text to integer value
+ *
  * \param val The text representing the device state.  Valid values are anything
  *        that comes after AST_DEVICE_ in one of the defined values.
+ *
  * \return The AST_DEVICE_ integer value
  */
 enum ast_device_state ast_devstate_val(const char *val);
 
 /*! 
  * \brief Search the Channels by Name
- * \param device like a dialstring
- * Search the Device in active channels by compare the channelname against 
- * the devicename. Compared are only the first chars to the first '-' char.
- * \retval an AST_DEVICE_UNKNOWN if no channel found
+ *
+ * \param device like a dial string
+ *
+ * Search the Device in active channels by compare the channel name against 
+ * the device name. Compared are only the first chars to the first '-' char.
+ *
+ * \retval AST_DEVICE_UNKNOWN if no channel found
  * \retval AST_DEVICE_INUSE if a channel is found
  */
 enum ast_device_state ast_parse_device_state(const char *device);
 
 /*! 
  * \brief Asks a channel for device state
- * \param device like a dialstring
- * Asks a channel for device state, data is  normaly a number from dialstring
+ *
+ * \param device like a dial string
+ *
+ * Asks a channel for device state, data is normally a number from a dial string
  * used by the low level module
- * Trys the channel devicestate callback if not supported search in the
+ * Tries the channel device state callback if not supported search in the
  * active channels list for the device.
- * \retval an AST_DEVICE_??? state
+ *
+ * \retval an AST_DEVICE_??? state 
  * \retval -1 on failure
  */
 enum ast_device_state ast_device_state(const char *device);
 
 /*! 
  * \brief Tells Asterisk the State for Device is changed
- * \param fmt devicename like a dialstring with format parameters
- * Asterisk polls the new extensionstates and calls the registered
+ *
+ * \param state the new state of the device
+ * \param fmt device name like a dial string with format parameters
+ *
+ * The new state of the device will be sent off to any subscribers
+ * of device states.  It will also be stored in the internal event
+ * cache.
+ *
+ * \retval 0 on success 
+ * \retval -1 on failure
+ *
+ * \note This is deprecated in favor of ast_devstate_changed()
+ */
+int ast_devstate_changed(enum ast_device_state state, const char *fmt, ...)
+	__attribute__ ((format (printf, 2, 3)));
+
+/*! 
+ * \brief Tells Asterisk the State for Device is changed
+ *
+ * \param state the new state of the device
+ * \param fmt device name like a dial string with format parameters
+ *
+ * The new state of the device will be sent off to any subscribers
+ * of device states.  It will also be stored in the internal event
+ * cache.
+ *
+ * \retval 0 on success 
+ * \retval -1 on failure
+ *
+ * \note This is deprecated in favor of ast_devstate_changed()
+ */
+int ast_devstate_changed_literal(enum ast_device_state state, const char *device);
+
+/*! 
+ * \brief Tells Asterisk the State for Device is changed
+ *
+ * \param fmt device name like a dial string with format parameters
+ *
+ * Asterisk polls the new extension states and calls the registered
  * callbacks for the changed extensions
- * \retval 0 on success
+ *
+ * \retval 0 on success 
  * \retval -1 on failure
+ *
+ * \note This is deprecated in favor of ast_devstate_changed()
  */
 int ast_device_state_changed(const char *fmt, ...)
 	__attribute__ ((format (printf, 1, 2)));
 
 /*! 
  * \brief Tells Asterisk the State for Device is changed 
- * \param device devicename like a dialstring
- * Asterisk polls the new extensionstates and calls the registered
+ *
+ * \param device device name like a dial string
+ *
+ * Asterisk polls the new extension states and calls the registered
  * callbacks for the changed extensions
- * \retval 0 on success
+ *
+ * \retval 0 on success 
  * \retval -1 on failure
+ *
+ * \note This is deprecated in favor of ast_devstate_changed_literal()
  */
 int ast_device_state_changed_literal(const char *device);
 
 /*! 
  * \brief Add device state provider 
+ *
  * \param label to use in hint, like label:object
  * \param callback Callback
+ *
  * \retval 0 success
  * \retval -1 failure
  */ 
@@ -132,9 +192,11 @@ int ast_devstate_prov_add(const char *label, ast_devstate_prov_cb_type callback)
 
 /*! 
  * \brief Remove device state provider 
+ *
  * \param label to use in hint, like label:object
+ *
+ * \retval -1 on failure 
  * \retval 0 on success
- * \retval -1 on failure
  */ 
 int ast_devstate_prov_del(const char *label);