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