/usr/include/asterisk/devicestate.h is in asterisk-dev 1:13.18.3~dfsg-1ubuntu4.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 | /*
* Asterisk -- An open source telephony toolkit.
*
* Copyright (C) 1999 - 2005, Digium, Inc.
*
* Mark Spencer <markster@digium.com>
*
* See http://www.asterisk.org for more information about
* the Asterisk project. Please do not directly contact
* any of the maintainers of this project for assistance;
* the project provides a web site, mailing lists and IRC
* channels for your use.
*
* This program is free software, distributed under the terms of
* the GNU General Public License Version 2. See the LICENSE file
* at the top of the source tree.
*/
/*! \file
* \brief Device state management
*
* To subscribe to device state changes, use the stasis_subscribe
* method. For an example, see apps/app_queue.c.
*
* \todo Currently, when the state of a device changes, the device state provider
* calls one of the functions defined here to queue an object to say that the
* state of a device has changed. However, this does not include the new state.
* Another thread processes these device state change objects and calls the
* device state provider's callback to figure out what the new state is. It
* would make a lot more sense for the new state to be included in the original
* function call that says the state of a device has changed. However, it
* will take a lot of work to change this.
*
* \arg See \ref AstExtState
*/
#ifndef _ASTERISK_DEVICESTATE_H
#define _ASTERISK_DEVICESTATE_H
#include "asterisk/channelstate.h"
#include "asterisk/utils.h"
#if defined(__cplusplus) || defined(c_plusplus)
extern "C" {
#endif
/*! \brief Device States
* \note The order of these states may not change because they are included
* in Asterisk events which may be transmitted across the network to
* other servers.
*/
enum ast_device_state {
AST_DEVICE_UNKNOWN, /*!< Device is valid but channel didn't know state */
AST_DEVICE_NOT_INUSE, /*!< Device is not used */
AST_DEVICE_INUSE, /*!< Device is in use */
AST_DEVICE_BUSY, /*!< Device is busy */
AST_DEVICE_INVALID, /*!< Device is invalid */
AST_DEVICE_UNAVAILABLE, /*!< Device is unavailable */
AST_DEVICE_RINGING, /*!< Device is ringing */
AST_DEVICE_RINGINUSE, /*!< Device is ringing *and* in use */
AST_DEVICE_ONHOLD, /*!< Device is on hold */
AST_DEVICE_TOTAL, /*!< Total num of device states, used for testing */
};
/*! \brief Device State Cachability
* \note This is used to define the cachability of a device state when set.
*/
enum ast_devstate_cache {
AST_DEVSTATE_NOT_CACHABLE, /*!< This device state is not cachable */
AST_DEVSTATE_CACHABLE, /*!< This device state is cachable */
};
/*! \brief Devicestate provider call back */
typedef enum ast_device_state (*ast_devstate_prov_cb_type)(const char *data);
/*!
* \brief Convert channel state to devicestate
*
* \param chanstate Current channel state
* \since 1.6.1
*/
enum ast_device_state ast_state_chan2dev(enum ast_channel_state chanstate);
/*!
* \brief Convert device state to text string for output
*
* \param devstate Current device state
*/
const char *devstate2str(enum ast_device_state devstate) attribute_pure __attribute__((deprecated));
const char *ast_devstate2str(enum ast_device_state devstate) attribute_pure;
/*!
* \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) attribute_pure;
/*!
* \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 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 dial string
*
* Asks a channel for device state, data is normally a number from a dial string
* used by the low level module
* Tries the channel device state callback if not supported search in the
* active channels list for the device.
*
* \retval an AST_DEVICE_??? state
*/
enum ast_device_state ast_device_state(const char *device);
/*!
* \brief Tells Asterisk the State for Device is changed
*
* \param state the new state of the device
* \param cachable whether this device state is cachable
* \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
*/
int ast_devstate_changed(enum ast_device_state state, enum ast_devstate_cache cachable, const char *fmt, ...)
__attribute__((format(printf, 3, 4)));
/*!
* \brief Tells Asterisk the State for Device is changed
*
* \param state the new state of the device
* \param cachable whether this device state is cachable
* \param device 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
*/
int ast_devstate_changed_literal(enum ast_device_state state, enum ast_devstate_cache cachable, const char *device);
/*!
* \brief Tells Asterisk the State for Device is changed.
* (Accept change notification, add it to change queue.)
*
* \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 -1 on failure
*
* \note This is deprecated in favor of ast_devstate_changed()
* \version 1.6.1 deprecated
*/
int ast_device_state_changed(const char *fmt, ...)
__attribute__((deprecated,format(printf, 1, 2)));
/*!
* \brief Tells Asterisk the State for Device is changed
*
* \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 -1 on failure
*
* \note This is deprecated in favor of ast_devstate_changed_literal()
* \version 1.6.1 deprecated
*/
int ast_device_state_changed_literal(const char *device)
__attribute__((deprecated));
/*!
* \brief Add device state provider
*
* \param label to use in hint, like label:object
* \param callback Callback
*
* \retval 0 success
* \retval -1 failure
*/
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
*/
int ast_devstate_prov_del(const char *label);
/*!
* \brief An object to hold state when calculating aggregate device state
*/
struct ast_devstate_aggregate;
/*!
* \brief Initialize aggregate device state
*
* \param[in] agg the state object
*
* \return nothing
* \since 1.6.1
*/
void ast_devstate_aggregate_init(struct ast_devstate_aggregate *agg);
/*!
* \brief Add a device state to the aggregate device state
*
* \param[in] agg the state object
* \param[in] state the state to add
*
* \return nothing
* \since 1.6.1
*/
void ast_devstate_aggregate_add(struct ast_devstate_aggregate *agg, enum ast_device_state state);
/*!
* \brief Get the aggregate device state result
*
* \param[in] agg the state object
*
* \return the aggregate device state after adding some number of device states.
* \since 1.6.1
*/
enum ast_device_state ast_devstate_aggregate_result(struct ast_devstate_aggregate *agg);
/*!
* \brief You shouldn't care about the contents of this struct
*
* This struct is only here so that it can be easily declared on the stack.
*/
struct ast_devstate_aggregate {
unsigned int ringing:1;
unsigned int inuse:1;
enum ast_device_state state;
};
/*!
* \brief The structure that contains device state
* \since 12
*/
struct ast_device_state_message {
/*! The name of the device */
const char *device;
/*!
* \brief The EID of the server where this message originated.
*
* \note A NULL EID means aggregate state.
*/
const struct ast_eid *eid;
/*! The state of the device */
enum ast_device_state state;
/*! Flag designating the cachability of this device state */
enum ast_devstate_cache cachable;
/*! The device and eid data is stuffed here when the struct is allocated. */
struct ast_eid stuff[0];
};
/*!
* \brief Get the Stasis topic for device state messages
* \retval The topic for device state messages
* \retval NULL if it has not been allocated
* \since 12
*/
struct stasis_topic *ast_device_state_topic_all(void);
/*!
* \brief Get the Stasis topic for device state messages for a specific device
* \param uniqueid The device for which to get the topic
* \retval The topic structure for MWI messages for a given device
* \retval NULL if it failed to be found or allocated
* \since 12
*/
struct stasis_topic *ast_device_state_topic(const char *device);
/*!
* \brief Get the Stasis caching topic for device state messages
* \retval The caching topic for device state messages
* \retval NULL if it has not been allocated
* \since 12
*/
struct stasis_topic *ast_device_state_topic_cached(void);
/*!
* \brief Backend cache for ast_device_state_topic_cached()
* \retval Cache of \ref ast_device_state_message.
* \since 12
*/
struct stasis_cache *ast_device_state_cache(void);
/*!
* \brief Get the Stasis message type for device state messages
* \retval The message type for device state messages
* \retval NULL if it has not been allocated
* \since 12
*/
struct stasis_message_type *ast_device_state_message_type(void);
/*!
* \brief Clear the device from the stasis cache.
* \param The device to clear
* \retval 0 if successful
* \retval -1 nothing to clear
* \since 12
*/
int ast_device_state_clear_cache(const char *device);
/*!
* \brief Initialize the device state core
* \retval 0 Success
* \retval -1 Failure
* \since 12
*/
int devstate_init(void);
/*!
* \brief Publish a device state update
* \param[in] device The device name
* \param[in] state The state of the device
* \param[in] cachable Whether the device state can be cached
* \retval 0 Success
* \retval -1 Failure
* \since 12
*/
#define ast_publish_device_state(device, state, cachable) \
ast_publish_device_state_full(device, state, cachable, &ast_eid_default)
/*!
* \brief Publish a device state update with EID
* \param[in] device The device name
* \param[in] state The state of the device
* \param[in] cachable Whether the device state can be cached
* \param[in] eid The EID of the server that originally published the message
* \retval 0 Success
* \retval -1 Failure
* \since 12
*/
int ast_publish_device_state_full(
const char *device,
enum ast_device_state state,
enum ast_devstate_cache cachable,
struct ast_eid *eid);
#if defined(__cplusplus) || defined(c_plusplus)
}
#endif
#endif /* _ASTERISK_DEVICESTATE_H */
|