Add Doxygen documentation for API changes from 1.6.0 to 1.6.1
[asterisk/asterisk.git] / include / asterisk / event.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2007 - 2008, 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 Allocate a subscription, but do not activate it
118  *
119  * \param type the event type to subscribe to
120  * \param cb the function to call when an event matches this subscription
121  * \param userdata data to pass to the provided callback
122  *
123  * This function should be used when you want to dynamically build a
124  * subscription.
125  *
126  * \return the allocated subscription, or NULL on failure
127  * \since 1.6.1
128  */
129 struct ast_event_sub *ast_event_subscribe_new(enum ast_event_type type,
130         ast_event_cb_t cb, void *userdata);
131
132 /*!
133  * \brief Destroy an allocated subscription
134  *
135  * \param sub the subscription to destroy
136  *
137  * This function should be used when a subscription is allocated with
138  * ast_event_subscribe_new(), but for some reason, you want to destroy it
139  * instead of activating it.  This could be because of an error when
140  * reading in the configuration for the dynamically built subscription.
141  * \since 1.6.1
142  */
143 void ast_event_sub_destroy(struct ast_event_sub *sub);
144
145 /*!
146  * \brief Append a uint parameter to a subscription
147  *
148  * \param sub the dynamic subscription allocated with ast_event_subscribe_new()
149  * \param ie_type the information element type for the parameter
150  * \param uint the value that must be present in the event to match this subscription
151  *
152  * \retval 0 success
153  * \retval non-zero failure
154  * \since 1.6.1
155  */
156 int ast_event_sub_append_ie_uint(struct ast_event_sub *sub,
157         enum ast_event_ie_type ie_type, uint32_t uint);
158
159 /*!
160  * \brief Append a string parameter to a subscription
161  *
162  * \param sub the dynamic subscription allocated with ast_event_subscribe_new()
163  * \param ie_type the information element type for the parameter
164  * \param str the string that must be present in the event to match this subscription
165  *
166  * \retval 0 success
167  * \retval non-zero failure
168  * \since 1.6.1
169  */
170 int ast_event_sub_append_ie_str(struct ast_event_sub *sub,
171         enum ast_event_ie_type ie_type, const char *str);
172
173 /*!
174  * \brief Append a raw parameter to a subscription
175  *
176  * \param sub the dynamic subscription allocated with ast_event_subscribe_new()
177  * \param ie_type the information element type for the parameter
178  * \param raw the data that must be present in the event to match this subscription
179  *
180  * \retval 0 success
181  * \retval non-zero failure
182  * \since 1.6.1
183  */
184 int ast_event_sub_append_ie_raw(struct ast_event_sub *sub,
185         enum ast_event_ie_type ie_type, void *data, size_t raw_datalen);
186
187 /*!
188  * \brief Append an 'exists' parameter to a subscription
189  *
190  * \param sub the dynamic subscription allocated with ast_event_subscribe_new()
191  * \param ie_type the information element type that must be present in the event
192  *      for it to match this subscription.
193  *
194  * \retval 0 success
195  * \retval non-zero failure
196  * \since 1.6.1
197  */
198 int ast_event_sub_append_ie_exists(struct ast_event_sub *sub,
199         enum ast_event_ie_type ie_type);
200
201 /*!
202  * \brief Activate a dynamically built subscription
203  *
204  * \param sub the subscription to activate that was allocated using
205  *      ast_event_subscribe_new()
206  *
207  * Once a dynamically built subscription has had all of the parameters added
208  * to it, it should be activated using this function.
209  *
210  * \retval 0 success
211  * \retval non-zero failure
212  * \since 1.6.1
213  */
214 int ast_event_sub_activate(struct ast_event_sub *sub);
215
216 /*!
217  * \brief Un-subscribe from events
218  *
219  * \param event_sub This is the reference to the subscription returned by
220  *        ast_event_subscribe.
221  *
222  * This function will remove a subscription and free the associated data
223  * structures.
224  *
225  * \return NULL for convenience.
226  * \version 1.6.1 return changed to NULL
227  */
228 struct ast_event_sub *ast_event_unsubscribe(struct ast_event_sub *event_sub);
229
230 /*!
231  * \brief Check if subscribers exist
232  *
233  * \param event_type This is the type of event that the caller would like to
234  *        check for subscribers to.
235  *
236  * The rest of the arguments to this function specify additional parameters for
237  * checking for subscriptions to subsets of an event type. The arguments must
238  * in sets of:
239  * \code
240  *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
241  * \endcode
242  * and must end with AST_EVENT_IE_END.
243  *
244  * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
245  * by a valid IE payload type.  If the payload type specified is
246  * AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided.
247  * Otherwise, a payload must also be specified.
248  *
249  * \return This returns one of the values defined in the ast_event_subscriber_res
250  *         enum which will indicate if subscribers exist that match the given
251  *         criteria.
252  *
253  * Example usage:
254  *
255  * \code
256  * if (ast_event_check_subscriber(AST_EVENT_MWI,
257  *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox,
258  *     AST_EVENT_IE_END) == AST_EVENT_SUB_NONE) {
259  *       return;
260  * }
261  * \endcode
262  *
263  * This example will check if there are any subscribers to MWI events for the
264  * mailbox defined in the "mailbox" variable.
265  */
266 enum ast_event_subscriber_res ast_event_check_subscriber(enum ast_event_type event_type, ...);
267
268 /*!
269  * \brief Report current subscriptions to a subscription subscriber
270  *
271  * \arg sub the subscription subscriber
272  *
273  * \return nothing
274  *
275  * This reports all of the current subscribers to a subscriber of
276  * subscribers to a specific event type.  (Try saying that a few times fast).
277  *
278  * The idea here is that it is sometimes very useful for a module to know when
279  * someone subscribes to events.  However, when they first subscribe, this
280  * provides that module the ability to request the event core report to them
281  * all of the subscriptions to that event type that already exist.
282  */
283 void ast_event_report_subs(const struct ast_event_sub *sub);
284
285 /*!
286  * \brief Dump the event cache for the subscriber
287  * \since 1.6.1
288  */
289 void ast_event_dump_cache(const struct ast_event_sub *event_sub);
290
291 /*!
292  * \brief Create a new event
293  *
294  * \param event_type The type of event to create
295  *
296  * The rest of the arguments to this function specify information elements to
297  * add to the event.  They are specified in the form:
298  * \code
299  *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
300  * \endcode
301  * and must end with AST_EVENT_IE_END.
302  *
303  * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
304  * by a valid IE payload type.  The payload type, EXISTS, should not be used here
305  * because it makes no sense to do so.  So, a payload must also be specified
306  * after the IE payload type.
307  *
308  * \return This returns the event that has been created.  If there is an error
309  *         creating the event, NULL will be returned.
310  *
311  * Example usage:
312  *
313  * \code
314  * if (!(event = ast_event_new(AST_EVENT_MWI,
315  *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox,
316  *     AST_EVENT_IE_NEWMSGS, AST_EVENT_IE_PLTYPE_UINT, new,
317  *     AST_EVENT_IE_OLDMSGS, AST_EVENT_IE_PLTYPE_UINT, old,
318  *     AST_EVENT_IE_END))) {
319  *       return;
320  * }
321  * \endcode
322  *
323  * This creates a MWI event with 3 information elements, a mailbox which is
324  * a string, and the number of new and old messages, specified as integers.
325  */
326 struct ast_event *ast_event_new(enum ast_event_type event_type, ...);
327
328 /*!
329  * \brief Destroy an event
330  *
331  * \param event the event to destroy
332  *
333  * \return Nothing
334  *
335  * \note Events that have been queued should *not* be destroyed by the code that
336  *       created the event.  It will be automatically destroyed after being
337  *       dispatched to the appropriate subscribers.
338  */
339 void ast_event_destroy(struct ast_event *event);
340
341 /*!
342  * \brief Queue an event
343  *
344  * \param event the event to be queued
345  *
346  * \retval zero success
347  * \retval non-zero failure
348  *
349  * This function queues an event to be dispatched to all of the appropriate
350  * subscribers.  This function will not block while the event is being
351  * dispatched because a pool of event dispatching threads handle the event
352  * queue.
353  */
354 int ast_event_queue(struct ast_event *event);
355
356 /*!
357  * \brief Queue and cache an event
358  *
359  * \param event the event to be queued and cached
360  *
361  * The rest of the arguments to this function specify information elements to
362  * use for determining which events in the cache that this event should replace.
363  * All events in the cache that match the specified criteria will be removed from
364  * the cache and then this one will be added.  The arguments are specified in
365  * the form:
366  *
367  * \code
368  *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype]
369  * \endcode
370  * and must end with AST_EVENT_IE_END.
371  *
372  * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
373  * by a valid IE payload type.  If the payload type given is EXISTS, then all
374  * events that contain that information element will be removed from the cache.
375  * Otherwise, all events in the cache that contain an information element with
376  * the same value as the new event will be removed.
377  *
378  * \note If more than one IE parameter is specified, they *all* must match for
379  *       the event to be removed from the cache.
380  *
381  * Example usage:
382  *
383  * \code
384  * ast_event_queue_and_cache(event,
385  *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR,
386  *     AST_EVENT_IE_END);
387  * \endcode
388  *
389  * This example queues and caches an event.  Any events in the cache that have
390  * the same MAILBOX information element as this event will be removed.
391  *
392  * The purpose of caching events is so that the core can retain the last known
393  * information for events that represent some sort of state.  That way, when
394  * code needs to find out the current state, it can query the cache.
395  */
396 int ast_event_queue_and_cache(struct ast_event *event, ...);
397
398 /*!
399  * \brief Retrieve an event from the cache
400  *
401  * \param ast_event_type The type of event to retrieve from the cache
402  *
403  * The rest of the arguments to this function specify information elements to
404  * match for retrieving events from the cache.  They are specified in the form:
405  * \code
406  *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
407  * \endcode
408  * and must end with AST_EVENT_IE_END.
409  *
410  * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
411  * by a valid IE payload type.  If the payload type specified is
412  * AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided.
413  * Otherwise, a payload must also be specified.
414  *
415  * \return A reference to an event retrieved from the cache.  If no event was
416  *         found that matches the specified criteria, then NULL will be returned.
417  *
418  * \note If more than one event in the cache matches the specified criteria, only
419  *       one will be returned, and it is undefined which one it will be.
420  *
421  * \note The caller of this function *must* call ast_event_destroy() on the
422  *       returned event after it is done using it.
423  *
424  * Example Usage:
425  *
426  * \code
427  * event = ast_event_get_cached(AST_EVENT_MWI,
428  *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox,
429  *     AST_EVENT_IE_END);
430  * \endcode
431  *
432  * This example will check for an MWI event in the cache that matches the
433  * specified mailbox.  This would be the way to find out the last known state
434  * of a mailbox without having to poll the mailbox directly.
435  */
436 struct ast_event *ast_event_get_cached(enum ast_event_type, ...);
437
438 /*!
439  * \brief Append an information element that has a string payload
440  *
441  * \param event the event that the IE will be appended to
442  * \param ie_type the type of IE to append
443  * \param str The string for the payload of the IE
444  *
445  * \retval 0 success
446  * \retval -1 failure
447  *
448  * The pointer to the event will get updated with the new location for the event
449  * that now contains the appended information element.  If the re-allocation of
450  * the memory for this event fails, it will be set to NULL.
451  */
452 int ast_event_append_ie_str(struct ast_event **event, enum ast_event_ie_type ie_type,
453         const char *str);
454
455 /*!
456  * \brief Append an information element that has an integer payload
457  *
458  * \param event the event that the IE will be appended to
459  * \param ie_type the type of IE to append
460  * \param data The integer for the payload of the IE
461  *
462  * \retval 0 success
463  * \retval -1 failure
464  *
465  * The pointer to the event will get updated with the new location for the event
466  * that now contains the appended information element.  If the re-allocation of
467  * the memory for this event fails, it will be set to NULL.
468  */
469 int ast_event_append_ie_uint(struct ast_event **event, enum ast_event_ie_type ie_type,
470         uint32_t data);
471
472 /*!
473  * \brief Append an information element that has a raw payload
474  *
475  * \param event the event that the IE will be appended to
476  * \param ie_type the type of IE to append
477  * \param data A pointer to the raw data for the payload of the IE
478  * \param data_len The amount of data to copy into the payload
479  *
480  * \retval 0 success
481  * \retval -1 failure
482  *
483  * The pointer to the event will get updated with the new location for the event
484  * that now contains the appended information element.  If the re-allocation of
485  * the memory for this event fails, it will be set to NULL.
486  */
487 int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_type,
488         const void *data, size_t data_len);
489
490 /*!
491  * \brief Get the value of an information element that has an integer payload
492  *
493  * \param event The event to get the IE from
494  * \param ie_type the type of information element to retrieve
495  *
496  * \return This returns the payload of the information element with the given type.
497  *         However, an IE with a payload of 0, and the case where no IE is found
498  *         yield the same return value.
499  */
500 uint32_t ast_event_get_ie_uint(const struct ast_event *event, enum ast_event_ie_type ie_type);
501
502 /*!
503  * \brief Get the value of an information element that has a string payload
504  *
505  * \param event The event to get the IE from
506  * \param ie_type the type of information element to retrieve
507  *
508  * \return This returns the payload of the information element with the given type.
509  *         If the information element isn't found, NULL will be returned.
510  */
511 const char *ast_event_get_ie_str(const struct ast_event *event, enum ast_event_ie_type ie_type);
512
513 /*!
514  * \brief Get the value of an information element that has a raw payload
515  *
516  * \param event The event to get the IE from
517  * \param ie_type the type of information element to retrieve
518  *
519  * \return This returns the payload of the information element with the given type.
520  *         If the information element isn't found, NULL will be returned.
521  */
522 const void *ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_ie_type ie_type);
523
524 /*!
525  * \brief Get the string representation of an information element type
526  *
527  * \param ie_type the information element type to get the string representation of
528  *
529  * \return the string representation of the information element type
530  * \since 1.6.1
531  */
532 const char *ast_event_get_ie_type_name(enum ast_event_ie_type ie_type);
533
534 /*!
535  * \brief Get the payload type for a given information element type
536  *
537  * \param ie_type the information element type to get the payload type of
538  *
539  * \return the payload type for the provided IE type
540  * \since 1.6.1
541  */
542 enum ast_event_ie_pltype ast_event_get_ie_pltype(enum ast_event_ie_type ie_type);
543
544 /*!
545  * \brief Get the type for an event
546  *
547  * \param event the event to get the type for
548  *
549  * \return the event type as represented by one of the values in the
550  *         ast_event_type enum
551  */
552 enum ast_event_type ast_event_get_type(const struct ast_event *event);
553
554 /*!
555  * \brief Get the string representation of the type of the given event
556  *
557  * \arg event the event to get the type of
558  *
559  * \return the string representation of the event type of the provided event
560  * \since 1.6.1
561  */
562 const char *ast_event_get_type_name(const struct ast_event *event);
563
564 /*!
565  * \brief Convert a string into an event type
566  *
567  * \param str the string to convert
568  * \param event_type an output parameter for the event type
569  *
570  * \retval 0 success
571  * \retval non-zero failure
572  * \since 1.6.1
573  */
574 int ast_event_str_to_event_type(const char *str, enum ast_event_type *event_type);
575
576 /*!
577  * \brief Convert a string to an IE type
578  *
579  * \param str the string to convert
580  * \param ie_type an output parameter for the IE type
581  *
582  * \retval 0 success
583  * \retval non-zero failure
584  * \since 1.6.1
585  */
586 int ast_event_str_to_ie_type(const char *str, enum ast_event_ie_type *ie_type);
587
588 /*!
589  * \brief Get the size of an event
590  *
591  * \param event the event to get the size of
592  *
593  * \return the number of bytes contained in the event
594  * \since 1.6.1
595  */
596 size_t ast_event_get_size(const struct ast_event *event);
597
598 /*!
599  * \brief Initialize an event iterator instance
600  *
601  * \param iterator The iterator instance to initialize
602  * \param event The event that will be iterated through
603  *
604  * \return Nothing
605  */
606 void ast_event_iterator_init(struct ast_event_iterator *iterator, const struct ast_event *event);
607
608 /*!
609  * \brief Move iterator instance to next IE
610  *
611  * \param iterator The iterator instance
612  *
613  * \retval 0 on success
614  * \retval -1 if end is reached
615  */
616 int ast_event_iterator_next(struct ast_event_iterator *iterator);
617
618 /*!
619  * \brief Get the type of the current IE in the iterator instance
620  *
621  * \param iterator The iterator instance
622  *
623  * \return the ie type as represented by one of the value sin the
624  *         ast_event_ie_type enum
625  */
626 enum ast_event_ie_type ast_event_iterator_get_ie_type(struct ast_event_iterator *iterator);
627
628 /*!
629  * \brief Get the value of the current IE in the ierator as an integer payload
630  *
631  * \param iterator The iterator instance
632  *
633  * \return This returns the payload of the information element as a uint.
634  */
635 uint32_t ast_event_iterator_get_ie_uint(struct ast_event_iterator *iterator);
636
637 /*!
638  * \brief Get the value of the current IE in the iterator as a string payload
639  *
640  * \param iterator The iterator instance
641  *
642  * \return This returns the payload of the information element as a string.
643  */
644 const char *ast_event_iterator_get_ie_str(struct ast_event_iterator *iterator);
645
646 /*!
647  * \brief Get the value of the current IE in the iterator instance that has a raw payload
648  *
649  * \param iterator The iterator instance
650  *
651  * \return This returns the payload of the information element as type raw.
652  */
653 void *ast_event_iterator_get_ie_raw(struct ast_event_iterator *iterator);
654
655 #if defined(__cplusplus) || defined(c_plusplus)
656 }
657 #endif
658
659 #endif /* AST_EVENT_H */