app_queue: Add LoginTime field for member in a queue.
[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 *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  * \retval 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  */
192 struct ast_devstate_aggregate;
193
194 /*!
195  * \brief Initialize aggregate device state
196  *
197  * \param[in] agg the state object
198  *
199  * \return nothing
200  * \since 1.6.1
201  */
202 void ast_devstate_aggregate_init(struct ast_devstate_aggregate *agg);
203
204 /*!
205  * \brief Add a device state to the aggregate device state
206  *
207  * \param[in] agg the state object
208  * \param[in] state the state to add
209  *
210  * \return nothing
211  * \since 1.6.1
212  */
213 void ast_devstate_aggregate_add(struct ast_devstate_aggregate *agg, enum ast_device_state state);
214
215 /*!
216  * \brief Get the aggregate device state result
217  *
218  * \param[in] agg the state object
219  *
220  * \return the aggregate device state after adding some number of device states.
221  * \since 1.6.1
222  */
223 enum ast_device_state ast_devstate_aggregate_result(struct ast_devstate_aggregate *agg);
224
225 /*!
226  * \brief You shouldn't care about the contents of this struct
227  *
228  * This struct is only here so that it can be easily declared on the stack.
229  */
230 struct ast_devstate_aggregate {
231         unsigned int ringing:1;
232         unsigned int inuse:1;
233         enum ast_device_state state;
234 };
235
236 /*!
237  * \brief The structure that contains device state
238  * \since 12
239  */
240 struct ast_device_state_message {
241         /*! The name of the device */
242         const char *device;
243         /*!
244          * \brief The EID of the server where this message originated.
245          *
246          * \note A NULL EID means aggregate state.
247          */
248         const struct ast_eid *eid;
249         /*! The state of the device */
250         enum ast_device_state state;
251         /*! Flag designating the cachability of this device state */
252         enum ast_devstate_cache cachable;
253         /*! The device and eid data is stuffed here when the struct is allocated. */
254         struct ast_eid stuff[0];
255 };
256
257 /*!
258  * \brief Get the Stasis topic for device state messages
259  * \retval The topic for device state messages
260  * \retval NULL if it has not been allocated
261  * \since 12
262  */
263 struct stasis_topic *ast_device_state_topic_all(void);
264
265 /*!
266  * \brief Get the Stasis topic for device state messages for a specific device
267  * \param uniqueid The device for which to get the topic
268  * \retval The topic structure for MWI messages for a given device
269  * \retval NULL if it failed to be found or allocated
270  * \since 12
271  */
272 struct stasis_topic *ast_device_state_topic(const char *device);
273
274 /*!
275  * \brief Get the Stasis caching topic for device state messages
276  * \retval The caching topic for device state messages
277  * \retval NULL if it has not been allocated
278  * \since 12
279  */
280 struct stasis_topic *ast_device_state_topic_cached(void);
281
282 /*!
283  * \brief Backend cache for ast_device_state_topic_cached()
284  * \retval Cache of \ref ast_device_state_message.
285  * \since 12
286  */
287 struct stasis_cache *ast_device_state_cache(void);
288
289 /*!
290  * \brief Get the Stasis message type for device state messages
291  * \retval The message type for device state messages
292  * \retval NULL if it has not been allocated
293  * \since 12
294  */
295 struct stasis_message_type *ast_device_state_message_type(void);
296
297 /*!
298  * \brief Clear the device from the stasis cache.
299  * \param The device to clear
300  * \retval 0 if successful
301  * \retval -1 nothing to clear
302  * \since 12
303  */
304 int ast_device_state_clear_cache(const char *device);
305
306 /*!
307  * \brief Initialize the device state core
308  * \retval 0 Success
309  * \retval -1 Failure
310  * \since 12
311  */
312 int devstate_init(void);
313
314 /*!
315  * \brief Publish a device state update
316  * \param[in] device The device name
317  * \param[in] state The state of the device
318  * \param[in] cachable Whether the device state can be cached
319  * \retval 0 Success
320  * \retval -1 Failure
321  * \since 12
322  */
323 #define ast_publish_device_state(device, state, cachable) \
324         ast_publish_device_state_full(device, state, cachable, &ast_eid_default)
325
326 /*!
327  * \brief Publish a device state update with EID
328  * \param[in] device The device name
329  * \param[in] state The state of the device
330  * \param[in] cachable Whether the device state can be cached
331  * \param[in] eid The EID of the server that originally published the message
332  * \retval 0 Success
333  * \retval -1 Failure
334  * \since 12
335  */
336 int ast_publish_device_state_full(
337                         const char *device,
338                         enum ast_device_state state,
339                         enum ast_devstate_cache cachable,
340                         struct ast_eid *eid);
341
342 #if defined(__cplusplus) || defined(c_plusplus)
343 }
344 #endif
345
346 #endif /* _ASTERISK_DEVICESTATE_H */