A lot of doxygen updates
[asterisk/asterisk.git] / include / asterisk / event.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2007, Digium, Inc.
5  *
6  * Russell Bryant <russell@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 /*!
20  * \file
21  * \author Russell Bryant <russell@digium.com>
22  * \ref AstGenericEvents
23  * \page AstGenericEvents Generic event system
24  *
25  * The purpose of this API is to provide a generic way to share events between
26  * Asterisk modules.  Code can generate events, and other code can subscribe to
27  * them.
28  *
29  * Events have an associated event type, as well as information elements.  The
30  * information elements are the meta data that go along with each event.  For
31  * example, in the case of message waiting indication, the event type is MWI,
32  * and each MWI event contains at least three information elements: the
33  * mailbox, the number of new messages, and the number of old messages.
34  *
35  * Subscriptions to events consist of an event type and information elements,
36  * as well.  Subscriptions can be to all events, or a certain subset of events.
37  * If an event type is provided, only events of that type will be sent to this
38  * subscriber.  Furthermore, if information elements are supplied with the
39  * subscription, only events that contain the specified information elements
40  * with specified values will be sent to the subscriber.  For example, when a
41  * SIP phone subscribes to MWI for mailbox 1234, then chan_sip can subscribe
42  * to internal Asterisk MWI events with the MAILBOX information element with
43  * a value of "1234".
44  *
45  * Another key feature of this event system is the ability to cache events.
46  * It is useful for some types of events to be able to remember the last known
47  * value.  These are usually events that indicate some kind of state change.
48  * In the example of MWI, app_voicemail can instruct the event core to cache
49  * these events based on the mailbox.  So, the last known MWI state of each
50  * mailbox will be cached, and other modules can retrieve this information
51  * on demand without having to poll the mailbox directly.
52  */
53
54 #ifndef AST_EVENT_H
55 #define AST_EVENT_H
56
57 #if defined(__cplusplus) || defined(c_plusplus)
58 extern "C" {
59 #endif
60
61 #include "asterisk/event_defs.h"
62
63 /*! 
64  * \brief Subscriber event callback type
65  *
66  * \param event the event being passed to the subscriber
67  * \param userdata the data provider in the call to ast_event_subscribe()
68  *
69  * \return The event callbacks do not return anything.
70  */
71 typedef void (*ast_event_cb_t)(const struct ast_event *event, void *userdata);
72
73 /*! 
74  * \brief Subscribe to events
75  *
76  * \param event_type The type of events to subscribe to
77  * \param cb The function to be called with events
78  * \param userdata data to be passed to the event callback
79  *
80  * The rest of the arguments to this function specify additional parameters for
81  * the subscription to filter which events are passed to this subscriber.  The
82  * arguments must be in sets of:
83  * \code
84  *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
85  * \endcode
86  * and must end with AST_EVENT_IE_END.
87  *
88  * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
89  * by a valid IE payload type.  If the payload type specified is
90  * AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided.
91  * Otherwise, a payload must also be specified.
92  *
93  * \return This returns a reference to the subscription for use with
94  *         un-subscribing later.  If there is a failure in creating the
95  *         subscription, NULL will be returned.
96  *
97  * Example usage:
98  *
99  * \code
100  * peer->mwi_event_sub = ast_event_subscribe(AST_EVENT_MWI, mwi_event_cb, peer,
101  *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, peer->mailbox,
102  *     AST_EVENT_IE_END);
103  * \endcode
104  *
105  * This creates a subscription to AST_EVENT_MWI events that contain an
106  * information element, AST_EVENT_IE_MAILBOX, with the same string value
107  * contained in peer->mailbox.  Also, the event callback will be passed a
108  * pointer to the peer.
109  */
110 struct ast_event_sub *ast_event_subscribe(enum ast_event_type event_type, 
111         ast_event_cb_t cb, void *userdata, ...);
112
113 /*!
114  * \brief Un-subscribe from events
115  *
116  * \param event_sub This is the reference to the subscription returned by
117  *        ast_event_subscribe.
118  * 
119  * \return Nothing
120  */
121 void ast_event_unsubscribe(struct ast_event_sub *event_sub);
122
123 /*!
124  * \brief Check if subscribers exist
125  *
126  * \param event_type This is the type of event that the caller would like to
127  *        check for subscribers to.
128  *
129  * The rest of the arguments to this function specify additional parameters for
130  * checking for subscriptions to subsets of an event type. The arguments must
131  * in sets of:
132  * \code
133  *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
134  * \endcode
135  * and must end with AST_EVENT_IE_END.
136  *
137  * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
138  * by a valid IE payload type.  If the payload type specified is
139  * AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided.
140  * Otherwise, a payload must also be specified.
141  *
142  * \return This returns one of the values defined in the ast_event_subscriber_res
143  *         enum which will indicate if subscribers exist that match the given
144  *         criteria.
145  *
146  * Example usage:
147  *
148  * \code
149  * if (ast_event_check_subscriber(AST_EVENT_MWI,
150  *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox,
151  *     AST_EVENT_IE_END) == AST_EVENT_SUB_NONE) {
152  *       return;
153  * }
154  * \endcode
155  *
156  * This example will check if there are any subscribers to MWI events for the 
157  * mailbox defined in the "mailbox" variable.
158  */
159 enum ast_event_subscriber_res ast_event_check_subscriber(enum ast_event_type event_type, ...);
160
161 /*!
162  * \brief Report current subscriptions to a subscription subscriber
163  *
164  * \arg sub the subscription subscriber
165  *
166  * \return nothing
167  *
168  * This reports all of the current subscribers to a subscriber of
169  * subscribers to a specific event type.  (Try saying that a few times fast).
170  *
171  * The idea here is that it is sometimes very useful for a module to know when
172  * someone subscribes to events.  However, when they first subscribe, this
173  * provides that module the ability to request the event core report to them
174  * all of the subscriptions to that event type that already exist.
175  */
176 void ast_event_report_subs(const struct ast_event_sub *sub);
177
178 /*!
179  * \brief Create a new event
180  *
181  * \param event_type The type of event to create
182  *
183  * The rest of the arguments to this function specify information elements to
184  * add to the event.  They are specified in the form:
185  * \code
186  *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
187  * \endcode
188  * and must end with AST_EVENT_IE_END.
189  *
190  * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
191  * by a valid IE payload type.  The payload type, EXISTS, should not be used here
192  * because it makes no sense to do so.  So, a payload must also be specified
193  * after the IE payload type.
194  *
195  * \return This returns the event that has been created.  If there is an error
196  *         creating the event, NULL will be returned.
197  *
198  * Example usage:
199  *
200  * \code
201  * if (!(event = ast_event_new(AST_EVENT_MWI,
202  *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox,
203  *     AST_EVENT_IE_NEWMSGS, AST_EVENT_IE_PLTYPE_UINT, new,
204  *     AST_EVENT_IE_OLDMSGS, AST_EVENT_IE_PLTYPE_UINT, old,
205  *     AST_EVENT_IE_END))) {
206  *       return;
207  * }
208  * \endcode
209  *
210  * This creates a MWI event with 3 information elements, a mailbox which is
211  * a string, and the number of new and old messages, specified as integers.
212  */
213 struct ast_event *ast_event_new(enum ast_event_type event_type, ...);
214
215 /*!
216  * \brief Destroy an event
217  *
218  * \param event the event to destroy
219  *
220  * \return Nothing
221  *
222  * \note Events that have been queued should *not* be destroyed by the code that
223  *       created the event.  It will be automatically destroyed after being
224  *       dispatched to the appropriate subscribers.
225  */
226 void ast_event_destroy(struct ast_event *event);
227
228 /*!
229  * \brief Queue an event
230  *
231  * \param event the event to be queued
232  *
233  * \retval zero success
234  * \retval non-zero failure
235  *
236  * This function queues an event to be dispatched to all of the appropriate
237  * subscribers.  This function will not block while the event is being
238  * dispatched because a pool of event dispatching threads handle the event 
239  * queue.
240  */
241 int ast_event_queue(struct ast_event *event);
242
243 /*!
244  * \brief Queue and cache an event
245  *
246  * \param event the event to be queued and cached
247  *
248  * The rest of the arguments to this function specify information elements to
249  * use for determining which events in the cache that this event should replace.
250  * All events in the cache that match the specified criteria will be removed from
251  * the cache and then this one will be added.  The arguments are specified in 
252  * the form:
253  *
254  * \code
255  *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype]
256  * \endcode
257  * and must end with AST_EVENT_IE_END.
258  *
259  * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
260  * by a valid IE payload type.  If the payload type given is EXISTS, then all
261  * events that contain that information element will be removed from the cache.
262  * Otherwise, all events in the cache that contain an information element with
263  * the same value as the new event will be removed.
264  *
265  * \note If more than one IE parameter is specified, they *all* must match for
266  *       the event to be removed from the cache.
267  *
268  * Example usage:
269  *
270  * \code
271  * ast_event_queue_and_cache(event,
272  *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR,
273  *     AST_EVENT_IE_END);
274  * \endcode
275  *
276  * This example queues and caches an event.  Any events in the cache that have
277  * the same MAILBOX information element as this event will be removed.
278  *
279  * The purpose of caching events is so that the core can retain the last known
280  * information for events that represent some sort of state.  That way, when
281  * code needs to find out the current state, it can query the cache.
282  */
283 int ast_event_queue_and_cache(struct ast_event *event, ...);
284
285 /*!
286  * \brief Retrieve an event from the cache
287  *
288  * \param ast_event_type The type of event to retrieve from the cache
289  *
290  * The rest of the arguments to this function specify information elements to
291  * match for retrieving events from the cache.  They are specified in the form:
292  * \code
293  *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
294  * \endcode
295  * and must end with AST_EVENT_IE_END.
296  *
297  * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
298  * by a valid IE payload type.  If the payload type specified is
299  * AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided.
300  * Otherwise, a payload must also be specified.
301  *
302  * \return A reference to an event retrieved from the cache.  If no event was
303  *         found that matches the specified criteria, then NULL will be returned.
304  *
305  * \note If more than one event in the cache matches the specified criteria, only
306  *       one will be returned, and it is undefined which one it will be.
307  *
308  * \note The caller of this function *must* call ast_event_destroy() on the
309  *       returned event after it is done using it.
310  *
311  * Example Usage:
312  *
313  * \code
314  * event = ast_event_get_cached(AST_EVENT_MWI,
315  *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox,
316  *     AST_EVENT_IE_END);
317  * \endcode
318  *
319  * This example will check for an MWI event in the cache that matches the
320  * specified mailbox.  This would be the way to find out the last known state
321  * of a mailbox without having to poll the mailbox directly.
322  */
323 struct ast_event *ast_event_get_cached(enum ast_event_type, ...);
324
325 /*!
326  * \brief Append an information element that has a string payload
327  *
328  * \param event the event that the IE will be appended to
329  * \param ie_type the type of IE to append
330  * \param str The string for the payload of the IE
331  *
332  * \retval 0 success
333  * \retval -1 failure
334  *
335  * The pointer to the event will get updated with the new location for the event
336  * that now contains the appended information element.  If the re-allocation of
337  * the memory for this event fails, it will be set to NULL.
338  */
339 int ast_event_append_ie_str(struct ast_event **event, enum ast_event_ie_type ie_type,
340         const char *str);
341
342 /*!
343  * \brief Append an information element that has an integer payload
344  *
345  * \param event the event that the IE will be appended to
346  * \param ie_type the type of IE to append
347  * \param data The integer for the payload of the IE
348  *
349  * \retval 0 success
350  * \retval -1 failure
351  *
352  * The pointer to the event will get updated with the new location for the event
353  * that now contains the appended information element.  If the re-allocation of
354  * the memory for this event fails, it will be set to NULL.
355  */
356 int ast_event_append_ie_uint(struct ast_event **event, enum ast_event_ie_type ie_type,
357         uint32_t data);
358
359 /*!
360  * \brief Append an information element that has a raw payload
361  *
362  * \param event the event that the IE will be appended to
363  * \param ie_type the type of IE to append
364  * \param data A pointer to the raw data for the payload of the IE
365  * \param data_len The amount of data to copy into the payload
366  *
367  * \retval 0 success
368  * \retval -1 failure
369  *
370  * The pointer to the event will get updated with the new location for the event
371  * that now contains the appended information element.  If the re-allocation of
372  * the memory for this event fails, it will be set to NULL.
373  */
374 int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_type,
375         const void *data, size_t data_len);
376
377 /*!
378  * \brief Get the value of an information element that has an integer payload
379  *
380  * \param event The event to get the IE from
381  * \param ie_type the type of information element to retrieve
382  * 
383  * \return This returns the payload of the information element with the given type.
384  *         However, an IE with a payload of 0, and the case where no IE is found
385  *         yield the same return value.
386  */
387 uint32_t ast_event_get_ie_uint(const struct ast_event *event, enum ast_event_ie_type ie_type);
388
389 /*!
390  * \brief Get the value of an information element that has a string payload
391  *
392  * \param event The event to get the IE from
393  * \param ie_type the type of information element to retrieve
394  * 
395  * \return This returns the payload of the information element with the given type.
396  *         If the information element isn't found, NULL will be returned.
397  */
398 const char *ast_event_get_ie_str(const struct ast_event *event, enum ast_event_ie_type ie_type);
399
400 /*!
401  * \brief Get the value of an information element that has a raw payload
402  *
403  * \param event The event to get the IE from
404  * \param ie_type the type of information element to retrieve
405  * 
406  * \return This returns the payload of the information element with the given type.
407  *         If the information element isn't found, NULL will be returned.
408  */
409 const void *ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_ie_type ie_type);
410
411 /*!
412  * \brief Get the type for an event
413  *
414  * \param event the event to get the type for
415  *
416  * \return the event type as represented by one of the values in the
417  *         ast_event_type enum
418  */
419 enum ast_event_type ast_event_get_type(const struct ast_event *event);
420
421 /*!
422  * \brief Initialize an event iterator instance
423  *
424  * \param iterator The iterator instance to initialize
425  * \param event The event that will be iterated through
426  *
427  * \return Nothing
428  */
429 void ast_event_iterator_init(struct ast_event_iterator *iterator, const struct ast_event *event);
430
431 /*!
432  * \brief Move iterator instance to next IE
433  *
434  * \param iterator The iterator instance
435  *
436  * \retval 0 on success
437  * \retval -1 if end is reached
438  */
439 int ast_event_iterator_next(struct ast_event_iterator *iterator);
440
441 /*!
442  * \brief Get the type of the current IE in the iterator instance
443  *
444  * \param iterator The iterator instance
445  *
446  * \return the ie type as represented by one of the value sin the
447  *         ast_event_ie_type enum
448  */
449 enum ast_event_ie_type ast_event_iterator_get_ie_type(struct ast_event_iterator *iterator);
450
451 /*!
452  * \brief Get the value of the current IE in the ierator as an integer payload
453  *
454  * \param iterator The iterator instance
455  *
456  * \return This returns the payload of the information element as a uint.
457  */
458 uint32_t ast_event_iterator_get_ie_uint(struct ast_event_iterator *iterator);
459
460 /*!
461  * \brief Get the value of the current IE in the iterator as a string payload
462  *
463  * \param iterator The iterator instance
464  *
465  * \return This returns the payload of the information element as a string.
466  */
467 const char *ast_event_iterator_get_ie_str(struct ast_event_iterator *iterator);
468
469 /*!
470  * \brief Get the value of the current IE in the iterator instance that has a raw payload
471  *
472  * \param iterator The iterator instance
473  *
474  * \return This returns the payload of the information element as type raw.
475  */
476 void *ast_event_iterator_get_ie_raw(struct ast_event_iterator *iterator);
477
478 #if defined(__cplusplus) || defined(c_plusplus)
479 }
480 #endif
481
482 #endif /* AST_EVENT_H */