Asterisk - The Open Source Telephony Project  GIT-master-a24979a
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 
40 #include "asterisk/channelstate.h"
41 #include "asterisk/utils.h"
42 
43 #if defined(__cplusplus) || defined(c_plusplus)
44 extern "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 */
74 typedef 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  */
89 const 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  */
96 const 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  */
106 enum 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  */
119 enum 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  */
133 enum 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  */
149 int 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  */
166 int 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  */
177 int 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  */
187 int 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;
231  enum ast_device_state state;
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 */
248  enum ast_device_state state;
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  */
270 struct 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  */
302 int 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  */
310 int 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,
336  enum ast_device_state state,
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 */
static snd_pcm_format_t format
Definition: chan_alsa.c:106
enum sip_cc_notify_state state
Definition: chan_sip.c:966
Channel states.
ast_channel_state
ast_channel states
Definition: channelstate.h:35
#define attribute_pure
Definition: compiler.h:35
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
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
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
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
enum ast_device_state ast_devstate_aggregate_result(struct ast_devstate_aggregate *agg)
Get the aggregate device state result.
Definition: devicestate.c:663
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
enum ast_device_state ast_state_chan2dev(enum ast_channel_state chanstate)
Convert channel state to devicestate.
Definition: devicestate.c:242
struct stasis_message_type * ast_device_state_message_type(void)
Get the Stasis message type for device state messages.
enum ast_device_state ast_parse_device_state(const char *device)
Search the Channels by Name.
Definition: devicestate.c:287
struct stasis_topic * ast_device_state_topic_all(void)
Get the Stasis topic for device state messages.
Definition: devicestate.c:668
int devstate_init(void)
Initialize the device state core.
Definition: devicestate.c:896
const char * ast_devstate2str(enum ast_device_state devstate) attribute_pure
Convert device state to text string for output.
Definition: devicestate.c:237
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
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
struct stasis_topic * ast_device_state_topic_cached(void)
Get the Stasis caching topic for device state messages.
Definition: devicestate.c:678
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
unsigned int ringing
Definition: devicestate.h:229
An Entity ID is essentially a MAC address, brief and unique.
Definition: utils.h:808
Definition: ast_expr2.c:325
Utility functions.