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