CLI: Create ast_cli_completion_vector.
[asterisk/asterisk.git] / include / asterisk / devicestate.h
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  */
52 enum ast_device_state {
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 cachability of a device state when set.
67  */
68 enum ast_devstate_cache {
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  */
82 enum ast_device_state ast_state_chan2dev(enum ast_channel_state chanstate);
83
84 /*!
85  * \brief Convert device state to text string for output
86  *
87  * \param devstate Current device state
88  */
89 const char *devstate2str(enum ast_device_state devstate) attribute_pure __attribute__((deprecated));
90 const char *ast_devstate2str(enum ast_device_state devstate) attribute_pure;
91
92 /*!
93  * \brief Convert device state to text string that is easier to parse
94  *
95  * \param devstate Current device state
96  */
97 const char *ast_devstate_str(enum ast_device_state devstate) attribute_pure;
98
99 /*!
100  * \brief Convert device state from text to integer value
101  *
102  * \param val The text representing the device state.  Valid values are anything
103  *        that comes after AST_DEVICE_ in one of the defined values.
104  *
105  * \return The AST_DEVICE_ integer value
106  */
107 enum ast_device_state ast_devstate_val(const char *val);
108
109 /*!
110  * \brief Search the Channels by Name
111  *
112  * \param device like a dial string
113  *
114  * Search the Device in active channels by compare the channel name against
115  * the device name. Compared are only the first chars to the first '-' char.
116  *
117  * \retval AST_DEVICE_UNKNOWN if no channel found
118  * \retval AST_DEVICE_INUSE if a channel is found
119  */
120 enum ast_device_state ast_parse_device_state(const char *device);
121
122 /*!
123  * \brief Asks a channel for device state
124  *
125  * \param device like a dial string
126  *
127  * Asks a channel for device state, data is normally a number from a dial string
128  * used by the low level module
129  * Tries the channel device state callback if not supported search in the
130  * active channels list for the device.
131  *
132  * \retval an AST_DEVICE_??? state
133  */
134 enum ast_device_state ast_device_state(const char *device);
135
136 /*!
137  * \brief Tells Asterisk the State for Device is changed
138  *
139  * \param state the new state of the device
140  * \param cachable whether this device state is cachable
141  * \param fmt device name like a dial string with format parameters
142  *
143  * The new state of the device will be sent off to any subscribers
144  * of device states.  It will also be stored in the internal event
145  * cache.
146  *
147  * \retval 0 on success
148  * \retval -1 on failure
149  */
150 int ast_devstate_changed(enum ast_device_state state, enum ast_devstate_cache cachable, const char *fmt, ...)
151         __attribute__((format(printf, 3, 4)));
152
153 /*!
154  * \brief Tells Asterisk the State for Device is changed
155  *
156  * \param state the new state of the device
157  * \param cachable whether this device state is cachable
158  * \param device device name like a dial string with format parameters
159  *
160  * The new state of the device will be sent off to any subscribers
161  * of device states.  It will also be stored in the internal event
162  * cache.
163  *
164  * \retval 0 on success
165  * \retval -1 on failure
166  */
167 int ast_devstate_changed_literal(enum ast_device_state state, enum ast_devstate_cache cachable, const char *device);
168
169 /*!
170  * \brief Tells Asterisk the State for Device is changed.
171  * (Accept change notification, add it to change queue.)
172  *
173  * \param fmt device name like a dial string with format parameters
174  *
175  * Asterisk polls the new extension states and calls the registered
176  * callbacks for the changed extensions
177  *
178  * \retval 0 on success
179  * \retval -1 on failure
180  *
181  * \note This is deprecated in favor of ast_devstate_changed()
182  * \version 1.6.1 deprecated
183  */
184 int ast_device_state_changed(const char *fmt, ...)
185         __attribute__((deprecated,format(printf, 1, 2)));
186
187 /*!
188  * \brief Tells Asterisk the State for Device is changed
189  *
190  * \param device device name like a dial string
191  *
192  * Asterisk polls the new extension states and calls the registered
193  * callbacks for the changed extensions
194  *
195  * \retval 0 on success
196  * \retval -1 on failure
197  *
198  * \note This is deprecated in favor of ast_devstate_changed_literal()
199  * \version 1.6.1 deprecated
200  */
201 int ast_device_state_changed_literal(const char *device)
202         __attribute__((deprecated));
203
204 /*!
205  * \brief Add device state provider
206  *
207  * \param label to use in hint, like label:object
208  * \param callback Callback
209  *
210  * \retval 0 success
211  * \retval -1 failure
212  */
213 int ast_devstate_prov_add(const char *label, ast_devstate_prov_cb_type callback);
214
215 /*!
216  * \brief Remove device state provider
217  *
218  * \param label to use in hint, like label:object
219  *
220  * \retval -1 on failure
221  * \retval 0 on success
222  */
223 int ast_devstate_prov_del(const char *label);
224
225 /*!
226  * \brief An object to hold state when calculating aggregate device state
227  */
228 struct ast_devstate_aggregate;
229
230 /*!
231  * \brief Initialize aggregate device state
232  *
233  * \param[in] agg the state object
234  *
235  * \return nothing
236  * \since 1.6.1
237  */
238 void ast_devstate_aggregate_init(struct ast_devstate_aggregate *agg);
239
240 /*!
241  * \brief Add a device state to the aggregate device state
242  *
243  * \param[in] agg the state object
244  * \param[in] state the state to add
245  *
246  * \return nothing
247  * \since 1.6.1
248  */
249 void ast_devstate_aggregate_add(struct ast_devstate_aggregate *agg, enum ast_device_state state);
250
251 /*!
252  * \brief Get the aggregate device state result
253  *
254  * \param[in] agg the state object
255  *
256  * \return the aggregate device state after adding some number of device states.
257  * \since 1.6.1
258  */
259 enum ast_device_state ast_devstate_aggregate_result(struct ast_devstate_aggregate *agg);
260
261 /*!
262  * \brief You shouldn't care about the contents of this struct
263  *
264  * This struct is only here so that it can be easily declared on the stack.
265  */
266 struct ast_devstate_aggregate {
267         unsigned int ringing:1;
268         unsigned int inuse:1;
269         enum ast_device_state state;
270 };
271
272 /*!
273  * \brief The structure that contains device state
274  * \since 12
275  */
276 struct ast_device_state_message {
277         /*! The name of the device */
278         const char *device;
279         /*!
280          * \brief The EID of the server where this message originated.
281          *
282          * \note A NULL EID means aggregate state.
283          */
284         const struct ast_eid *eid;
285         /*! The state of the device */
286         enum ast_device_state state;
287         /*! Flag designating the cachability of this device state */
288         enum ast_devstate_cache cachable;
289         /*! The device and eid data is stuffed here when the struct is allocated. */
290         struct ast_eid stuff[0];
291 };
292
293 /*!
294  * \brief Get the Stasis topic for device state messages
295  * \retval The topic for device state messages
296  * \retval NULL if it has not been allocated
297  * \since 12
298  */
299 struct stasis_topic *ast_device_state_topic_all(void);
300
301 /*!
302  * \brief Get the Stasis topic for device state messages for a specific device
303  * \param uniqueid The device for which to get the topic
304  * \retval The topic structure for MWI messages for a given device
305  * \retval NULL if it failed to be found or allocated
306  * \since 12
307  */
308 struct stasis_topic *ast_device_state_topic(const char *device);
309
310 /*!
311  * \brief Get the Stasis caching topic for device state messages
312  * \retval The caching topic for device state messages
313  * \retval NULL if it has not been allocated
314  * \since 12
315  */
316 struct stasis_topic *ast_device_state_topic_cached(void);
317
318 /*!
319  * \brief Backend cache for ast_device_state_topic_cached()
320  * \retval Cache of \ref ast_device_state_message.
321  * \since 12
322  */
323 struct stasis_cache *ast_device_state_cache(void);
324
325 /*!
326  * \brief Get the Stasis message type for device state messages
327  * \retval The message type for device state messages
328  * \retval NULL if it has not been allocated
329  * \since 12
330  */
331 struct stasis_message_type *ast_device_state_message_type(void);
332
333 /*!
334  * \brief Clear the device from the stasis cache.
335  * \param The device to clear
336  * \retval 0 if successful
337  * \retval -1 nothing to clear
338  * \since 12
339  */
340 int ast_device_state_clear_cache(const char *device);
341
342 /*!
343  * \brief Initialize the device state core
344  * \retval 0 Success
345  * \retval -1 Failure
346  * \since 12
347  */
348 int devstate_init(void);
349
350 /*!
351  * \brief Publish a device state update
352  * \param[in] device The device name
353  * \param[in] state The state of the device
354  * \param[in] cachable Whether the device state can be cached
355  * \retval 0 Success
356  * \retval -1 Failure
357  * \since 12
358  */
359 #define ast_publish_device_state(device, state, cachable) \
360         ast_publish_device_state_full(device, state, cachable, &ast_eid_default)
361
362 /*!
363  * \brief Publish a device state update with EID
364  * \param[in] device The device name
365  * \param[in] state The state of the device
366  * \param[in] cachable Whether the device state can be cached
367  * \param[in] eid The EID of the server that originally published the message
368  * \retval 0 Success
369  * \retval -1 Failure
370  * \since 12
371  */
372 int ast_publish_device_state_full(
373                         const char *device,
374                         enum ast_device_state state,
375                         enum ast_devstate_cache cachable,
376                         struct ast_eid *eid);
377
378 #if defined(__cplusplus) || defined(c_plusplus)
379 }
380 #endif
381
382 #endif /* _ASTERISK_DEVICESTATE_H */