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