Merge a set of device state improvements from team/russell/events.
[asterisk/asterisk.git] / include / asterisk / devicestate.h
index 08c5476..8ef0b24 100644 (file)
@@ -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);