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