Improve performance of the ast_event cache functionality.
[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  * \details
362  * The purpose of caching events is so that the core can retain the last known
363  * information for events that represent some sort of state.  That way, when
364  * code needs to find out the current state, it can query the cache.
365  *
366  * The event API already knows which events can be cached and how to cache them.
367  *
368  * \retval 0 success
369  * \retval non-zero failure.  If failure is returned, the event must be destroyed
370  *         by the caller of this function.
371  */
372 int ast_event_queue_and_cache(struct ast_event *event);
373
374 /*!
375  * \brief Retrieve an event from the cache
376  *
377  * \param ast_event_type The type of event to retrieve from the cache
378  *
379  * The rest of the arguments to this function specify information elements to
380  * match for retrieving events from the cache.  They are specified in the form:
381  * \code
382  *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
383  * \endcode
384  * and must end with AST_EVENT_IE_END.
385  *
386  * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
387  * by a valid IE payload type.  If the payload type specified is
388  * AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided.
389  * Otherwise, a payload must also be specified.
390  *
391  * \return A reference to an event retrieved from the cache.  If no event was
392  *         found that matches the specified criteria, then NULL will be returned.
393  *
394  * \note If more than one event in the cache matches the specified criteria, only
395  *       one will be returned, and it is undefined which one it will be.
396  *
397  * \note The caller of this function *must* call ast_event_destroy() on the
398  *       returned event after it is done using it.
399  *
400  * Example Usage:
401  *
402  * \code
403  * event = ast_event_get_cached(AST_EVENT_MWI,
404  *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox,
405  *     AST_EVENT_IE_END);
406  * \endcode
407  *
408  * This example will check for an MWI event in the cache that matches the
409  * specified mailbox.  This would be the way to find out the last known state
410  * of a mailbox without having to poll the mailbox directly.
411  */
412 struct ast_event *ast_event_get_cached(enum ast_event_type, ...);
413
414 /*!
415  * \brief Append an information element that has a string payload
416  *
417  * \param event the event that the IE will be appended to
418  * \param ie_type the type of IE to append
419  * \param str The string for the payload of the IE
420  *
421  * \retval 0 success
422  * \retval -1 failure
423  *
424  * The pointer to the event will get updated with the new location for the event
425  * that now contains the appended information element.  If the re-allocation of
426  * the memory for this event fails, it will be set to NULL.
427  */
428 int ast_event_append_ie_str(struct ast_event **event, enum ast_event_ie_type ie_type,
429         const char *str);
430
431 /*!
432  * \brief Append an information element that has an integer payload
433  *
434  * \param event the event that the IE will be appended to
435  * \param ie_type the type of IE to append
436  * \param data The integer for the payload of the IE
437  *
438  * \retval 0 success
439  * \retval -1 failure
440  *
441  * The pointer to the event will get updated with the new location for the event
442  * that now contains the appended information element.  If the re-allocation of
443  * the memory for this event fails, it will be set to NULL.
444  */
445 int ast_event_append_ie_uint(struct ast_event **event, enum ast_event_ie_type ie_type,
446         uint32_t data);
447
448 /*!
449  * \brief Append an information element that has a raw payload
450  *
451  * \param event the event that the IE will be appended to
452  * \param ie_type the type of IE to append
453  * \param data A pointer to the raw data for the payload of the IE
454  * \param data_len The amount of data to copy into the payload
455  *
456  * \retval 0 success
457  * \retval -1 failure
458  *
459  * The pointer to the event will get updated with the new location for the event
460  * that now contains the appended information element.  If the re-allocation of
461  * the memory for this event fails, it will be set to NULL.
462  */
463 int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_type,
464         const void *data, size_t data_len);
465
466 /*!
467  * \brief Get the value of an information element that has an integer payload
468  *
469  * \param event The event to get the IE from
470  * \param ie_type the type of information element to retrieve
471  *
472  * \return This returns the payload of the information element with the given type.
473  *         However, an IE with a payload of 0, and the case where no IE is found
474  *         yield the same return value.
475  */
476 uint32_t ast_event_get_ie_uint(const struct ast_event *event, enum ast_event_ie_type ie_type);
477
478 /*!
479  * \brief Get the value of an information element that has a string payload
480  *
481  * \param event The event to get the IE from
482  * \param ie_type the type of information element to retrieve
483  *
484  * \return This returns the payload of the information element with the given type.
485  *         If the information element isn't found, NULL will be returned.
486  */
487 const char *ast_event_get_ie_str(const struct ast_event *event, enum ast_event_ie_type ie_type);
488
489 /*!
490  * \brief Get the hash for the string payload of an IE
491  *
492  * \param event The event to get the IE from
493  * \param ie_type the type of information element to retrieve the hash for
494  *
495  * \return This function returns the hash value as calculated by ast_str_hash()
496  *         for the string payload.  This is stored in the event to avoid
497  *         unnecessary string comparisons.
498  */
499 uint32_t ast_event_get_ie_str_hash(const struct ast_event *event, enum ast_event_ie_type ie_type);
500
501 /*!
502  * \brief Get the value of an information element that has a raw payload
503  *
504  * \param event The event to get the IE from
505  * \param ie_type the type of information element to retrieve
506  *
507  * \return This returns the payload of the information element with the given type.
508  *         If the information element isn't found, NULL will be returned.
509  */
510 const void *ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_ie_type ie_type);
511
512 /*!
513  * \brief Get the string representation of an information element type
514  *
515  * \param ie_type the information element type to get the string representation of
516  *
517  * \return the string representation of the information element type
518  * \since 1.6.1
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  * \param ie_type the information element type to get the payload type of
526  *
527  * \return the payload type for the provided IE type
528  * \since 1.6.1
529  */
530 enum ast_event_ie_pltype ast_event_get_ie_pltype(enum ast_event_ie_type ie_type);
531
532 /*!
533  * \brief Get the type for an event
534  *
535  * \param event the event to get the type for
536  *
537  * \return the event type as represented by one of the values in the
538  *         ast_event_type enum
539  */
540 enum ast_event_type ast_event_get_type(const struct ast_event *event);
541
542 /*!
543  * \brief Get the string representation of the type of the given event
544  *
545  * \arg event the event to get the type of
546  *
547  * \return the string representation of the event type of the provided event
548  * \since 1.6.1
549  */
550 const char *ast_event_get_type_name(const struct ast_event *event);
551
552 /*!
553  * \brief Convert a string into an event type
554  *
555  * \param str the string to convert
556  * \param event_type an output parameter for the event type
557  *
558  * \retval 0 success
559  * \retval non-zero failure
560  * \since 1.6.1
561  */
562 int ast_event_str_to_event_type(const char *str, enum ast_event_type *event_type);
563
564 /*!
565  * \brief Convert a string to an IE type
566  *
567  * \param str the string to convert
568  * \param ie_type an output parameter for the IE type
569  *
570  * \retval 0 success
571  * \retval non-zero failure
572  * \since 1.6.1
573  */
574 int ast_event_str_to_ie_type(const char *str, enum ast_event_ie_type *ie_type);
575
576 /*!
577  * \brief Get the size of an event
578  *
579  * \param event the event to get the size of
580  *
581  * \return the number of bytes contained in the event
582  * \since 1.6.1
583  */
584 size_t ast_event_get_size(const struct ast_event *event);
585
586 /*!
587  * \brief Initialize an event iterator instance
588  *
589  * \param iterator The iterator instance to initialize
590  * \param event The event that will be iterated through
591  *
592  * \return Nothing
593  */
594 void ast_event_iterator_init(struct ast_event_iterator *iterator, const struct ast_event *event);
595
596 /*!
597  * \brief Move iterator instance to next IE
598  *
599  * \param iterator The iterator instance
600  *
601  * \retval 0 on success
602  * \retval -1 if end is reached
603  */
604 int ast_event_iterator_next(struct ast_event_iterator *iterator);
605
606 /*!
607  * \brief Get the type of the current IE in the iterator instance
608  *
609  * \param iterator The iterator instance
610  *
611  * \return the ie type as represented by one of the value sin the
612  *         ast_event_ie_type enum
613  */
614 enum ast_event_ie_type ast_event_iterator_get_ie_type(struct ast_event_iterator *iterator);
615
616 /*!
617  * \brief Get the value of the current IE in the ierator as an integer payload
618  *
619  * \param iterator The iterator instance
620  *
621  * \return This returns the payload of the information element as a uint.
622  */
623 uint32_t ast_event_iterator_get_ie_uint(struct ast_event_iterator *iterator);
624
625 /*!
626  * \brief Get the value of the current IE in the iterator as a string payload
627  *
628  * \param iterator The iterator instance
629  *
630  * \return This returns the payload of the information element as a string.
631  */
632 const char *ast_event_iterator_get_ie_str(struct ast_event_iterator *iterator);
633
634 /*!
635  * \brief Get the value of the current IE in the iterator instance that has a raw payload
636  *
637  * \param iterator The iterator instance
638  *
639  * \return This returns the payload of the information element as type raw.
640  */
641 void *ast_event_iterator_get_ie_raw(struct ast_event_iterator *iterator);
642
643 #if defined(__cplusplus) || defined(c_plusplus)
644 }
645 #endif
646
647 #endif /* AST_EVENT_H */