00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 1999 - 2005, Digium, Inc. 00005 * 00006 * Mark Spencer <markster@digium.com> 00007 * 00008 * See http://www.asterisk.org for more information about 00009 * the Asterisk project. Please do not directly contact 00010 * any of the maintainers of this project for assistance; 00011 * the project provides a web site, mailing lists and IRC 00012 * channels for your use. 00013 * 00014 * This program is free software, distributed under the terms of 00015 * the GNU General Public License Version 2. See the LICENSE file 00016 * at the top of the source tree. 00017 */ 00018 00019 /*! \file 00020 * \brief Device state management 00021 */ 00022 00023 #ifndef _ASTERISK_DEVICESTATE_H 00024 #define _ASTERISK_DEVICESTATE_H 00025 00026 #if defined(__cplusplus) || defined(c_plusplus) 00027 extern "C" { 00028 #endif 00029 00030 enum ast_device_state { 00031 AST_DEVICE_UNKNOWN, /*!< Device is valid but channel didn't know state */ 00032 AST_DEVICE_NOT_INUSE, /*!< Device is not used */ 00033 AST_DEVICE_INUSE, /*!< Device is in use */ 00034 AST_DEVICE_BUSY, /*!< Device is busy */ 00035 AST_DEVICE_INVALID, /*!< Device is invalid */ 00036 AST_DEVICE_UNAVAILABLE, /*!< Device is unavailable */ 00037 AST_DEVICE_RINGING, /*!< Device is ringing */ 00038 AST_DEVICE_RINGINUSE, /*!< Device is ringing *and* in use */ 00039 AST_DEVICE_ONHOLD, /*!< Device is on hold */ 00040 AST_DEVICE_TOTAL, /*!< Total num of device states, used for testing */ 00041 }; 00042 00043 /*! \brief Devicestate watcher call back */ 00044 typedef int (*ast_devstate_cb_type)(const char *dev, int state, void *data); 00045 00046 /*! \brief Devicestate provider call back */ 00047 typedef int (*ast_devstate_prov_cb_type)(const char *data); 00048 00049 /*! \brief Convert device state to text string for output 00050 * \param devstate Current device state 00051 */ 00052 const char *devstate2str(enum ast_device_state devstate); 00053 00054 /*! \brief Search the Channels by Name 00055 * \param device like a dialstring 00056 * Search the Device in active channels by compare the channelname against 00057 * the devicename. Compared are only the first chars to the first '-' char. 00058 * Returns an AST_DEVICE_UNKNOWN if no channel found or 00059 * AST_DEVICE_INUSE if a channel is found 00060 */ 00061 int ast_parse_device_state(const char *device); 00062 00063 /*! \brief Asks a channel for device state 00064 * \param device like a dialstring 00065 * Asks a channel for device state, data is normaly a number from dialstring 00066 * used by the low level module 00067 * Trys the channel devicestate callback if not supported search in the 00068 * active channels list for the device. 00069 * Returns an AST_DEVICE_??? state -1 on failure 00070 */ 00071 int ast_device_state(const char *device); 00072 00073 /*! \brief Tells Asterisk the State for Device is changed 00074 * \param fmt devicename like a dialstring with format parameters 00075 * Asterisk polls the new extensionstates and calls the registered 00076 * callbacks for the changed extensions 00077 * Returns 0 on success, -1 on failure 00078 */ 00079 int ast_device_state_changed(const char *fmt, ...) 00080 __attribute__((format(printf, 1, 2))); 00081 00082 00083 /*! \brief Tells Asterisk the State for Device is changed 00084 * \param device devicename like a dialstring 00085 * Asterisk polls the new extensionstates and calls the registered 00086 * callbacks for the changed extensions 00087 * Returns 0 on success, -1 on failure 00088 */ 00089 int ast_device_state_changed_literal(const char *device); 00090 00091 /*! \brief Registers a device state change callback 00092 * \param callback Callback 00093 * \param data to pass to callback 00094 * The callback is called if the state for extension is changed 00095 * Return -1 on failure, ID on success 00096 */ 00097 int ast_devstate_add(ast_devstate_cb_type callback, void *data); 00098 00099 /*! \brief Unregisters a device state change callback 00100 * \param callback Callback 00101 * \param data to pass to callback 00102 * The callback is called if the state for extension is changed 00103 * Return -1 on failure, ID on success 00104 */ 00105 void ast_devstate_del(ast_devstate_cb_type callback, void *data); 00106 00107 /*! \brief Add device state provider 00108 * \param label to use in hint, like label:object 00109 * \param callback Callback 00110 * \retval -1 failure 00111 * \retval 0 success 00112 */ 00113 int ast_devstate_prov_add(const char *label, ast_devstate_prov_cb_type callback); 00114 00115 /*! \brief Remove device state provider 00116 * \param label to use in hint, like label:object 00117 * \return nothing 00118 */ 00119 void ast_devstate_prov_del(const char *label); 00120 00121 /*! 00122 * \brief An object to hold state when calculating aggregate device state 00123 */ 00124 struct ast_devstate_aggregate; 00125 00126 /*! 00127 * \brief Initialize aggregate device state 00128 * 00129 * \param[in] agg the state object 00130 * 00131 * \return nothing 00132 */ 00133 void ast_devstate_aggregate_init(struct ast_devstate_aggregate *agg); 00134 00135 /*! 00136 * \brief Add a device state to the aggregate device state 00137 * 00138 * \param[in] agg the state object 00139 * \param[in] state the state to add 00140 * 00141 * \return nothing 00142 */ 00143 void ast_devstate_aggregate_add(struct ast_devstate_aggregate *agg, enum ast_device_state state); 00144 00145 /*! 00146 * \brief Get the aggregate device state result 00147 * 00148 * \param[in] agg the state object 00149 * 00150 * \return the aggregate device state after adding some number of device states. 00151 */ 00152 enum ast_device_state ast_devstate_aggregate_result(struct ast_devstate_aggregate *agg); 00153 00154 /*! 00155 * \brief You shouldn't care about the contents of this struct 00156 * 00157 * This struct is only here so that it can be easily declared on the stack. 00158 */ 00159 struct ast_devstate_aggregate { 00160 unsigned int all_unavail:1; 00161 unsigned int all_busy:1; 00162 unsigned int all_free:1; 00163 unsigned int all_unknown:1; 00164 unsigned int on_hold:1; 00165 unsigned int busy:1; 00166 unsigned int in_use:1; 00167 unsigned int ring:1; 00168 }; 00169 00170 int ast_device_state_engine_init(void); 00171 00172 #if defined(__cplusplus) || defined(c_plusplus) 00173 } 00174 #endif 00175 00176 #endif /* _ASTERISK_DEVICESTATE_H */