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