90e27b2f6c6932ee3cbe5c65011aca47d2034d88
[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 description Description of the subscription.
82  * \param userdata data to be passed to the event callback
83  *
84  * The rest of the arguments to this function specify additional parameters for
85  * the subscription to filter which events are passed to this subscriber.  The
86  * arguments must be in sets of:
87  * \code
88  *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
89  * \endcode
90  * and must end with AST_EVENT_IE_END.
91  *
92  * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
93  * by a valid IE payload type.  If the payload type specified is
94  * AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided.
95  * Otherwise, a payload must also be specified.
96  *
97  * \return This returns a reference to the subscription for use with
98  *         un-subscribing later.  If there is a failure in creating the
99  *         subscription, NULL will be returned.
100  *
101  * Example usage:
102  *
103  * \code
104  * peer->mwi_event_sub = ast_event_subscribe(AST_EVENT_MWI, mwi_event_cb, peer,
105  *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, peer->mailbox,
106  *     AST_EVENT_IE_END);
107  * \endcode
108  *
109  * This creates a subscription to AST_EVENT_MWI events that contain an
110  * information element, AST_EVENT_IE_MAILBOX, with the same string value
111  * contained in peer->mailbox.  Also, the event callback will be passed a
112  * pointer to the peer.
113  *
114  * \note A NULL description will cause this function to crash, so watch out!
115  */
116 struct ast_event_sub *ast_event_subscribe(enum ast_event_type event_type,
117        ast_event_cb_t cb, const char *description, void *userdata, ...);
118
119 /*!
120  * \brief Allocate a subscription, but do not activate it
121  *
122  * \param type the event type to subscribe to
123  * \param cb the function to call when an event matches this subscription
124  * \param userdata data to pass to the provided callback
125  *
126  * This function should be used when you want to dynamically build a
127  * subscription.
128  *
129  * \return the allocated subscription, or NULL on failure
130  * \since 1.6.1
131  */
132 struct ast_event_sub *ast_event_subscribe_new(enum ast_event_type type,
133         ast_event_cb_t cb, void *userdata);
134
135 /*!
136  * \brief Destroy an allocated subscription
137  *
138  * \param sub the subscription to destroy
139  *
140  * This function should be used when a subscription is allocated with
141  * ast_event_subscribe_new(), but for some reason, you want to destroy it
142  * instead of activating it.  This could be because of an error when
143  * reading in the configuration for the dynamically built subscription.
144  * \since 1.6.1
145  */
146 void ast_event_sub_destroy(struct ast_event_sub *sub);
147
148 /*!
149  * \brief Append a uint parameter to a subscription
150  *
151  * \param sub the dynamic subscription allocated with ast_event_subscribe_new()
152  * \param ie_type the information element type for the parameter
153  * \param uint the value that must be present in the event to match this subscription
154  *
155  * \retval 0 success
156  * \retval non-zero failure
157  * \since 1.6.1
158  */
159 int ast_event_sub_append_ie_uint(struct ast_event_sub *sub,
160         enum ast_event_ie_type ie_type, uint32_t uint);
161
162 /*!
163  * \brief Append a bitflags parameter to a subscription
164  *
165  * \param sub the dynamic subscription allocated with ast_event_subscribe_new()
166  * \param ie_type the information element type for the parameter
167  * \param flags the flags that must be present in the event to match this subscription
168  *
169  * \retval 0 success
170  * \retval non-zero failure
171  * \since 1.8
172  */
173 int ast_event_sub_append_ie_bitflags(struct ast_event_sub *sub,
174         enum ast_event_ie_type ie_type, uint32_t flags);
175
176 /*!
177  * \brief Append a string parameter to a subscription
178  *
179  * \param sub the dynamic subscription allocated with ast_event_subscribe_new()
180  * \param ie_type the information element type for the parameter
181  * \param str the string that must be present in the event to match this subscription
182  *
183  * \retval 0 success
184  * \retval non-zero failure
185  * \since 1.6.1
186  */
187 int ast_event_sub_append_ie_str(struct ast_event_sub *sub,
188         enum ast_event_ie_type ie_type, const char *str);
189
190 /*!
191  * \brief Append a raw parameter to a subscription
192  *
193  * \param sub the dynamic subscription allocated with ast_event_subscribe_new()
194  * \param ie_type the information element type for the parameter
195  * \param data the data that must be present in the event to match this subscription
196  * \param raw_datalen length of data
197  *
198  * \retval 0 success
199  * \retval non-zero failure
200  * \since 1.6.1
201  */
202 int ast_event_sub_append_ie_raw(struct ast_event_sub *sub,
203         enum ast_event_ie_type ie_type, void *data, size_t raw_datalen);
204
205 /*!
206  * \brief Append an 'exists' parameter to a subscription
207  *
208  * \param sub the dynamic subscription allocated with ast_event_subscribe_new()
209  * \param ie_type the information element type that must be present in the event
210  *      for it to match this subscription.
211  *
212  * \retval 0 success
213  * \retval non-zero failure
214  * \since 1.6.1
215  */
216 int ast_event_sub_append_ie_exists(struct ast_event_sub *sub,
217         enum ast_event_ie_type ie_type);
218
219 /*!
220  * \brief Activate a dynamically built subscription
221  *
222  * \param sub the subscription to activate that was allocated using
223  *      ast_event_subscribe_new()
224  *
225  * Once a dynamically built subscription has had all of the parameters added
226  * to it, it should be activated using this function.
227  *
228  * \retval 0 success
229  * \retval non-zero failure
230  * \since 1.6.1
231  */
232 int ast_event_sub_activate(struct ast_event_sub *sub);
233
234 /*!
235  * \brief Un-subscribe from events
236  *
237  * \param event_sub This is the reference to the subscription returned by
238  *        ast_event_subscribe.
239  *
240  * This function will remove a subscription and free the associated data
241  * structures.
242  *
243  * \return NULL for convenience.
244  * \version 1.6.1 return changed to NULL
245  */
246 struct ast_event_sub *ast_event_unsubscribe(struct ast_event_sub *event_sub);
247
248 /*!
249  * \brief Get description for a subscription
250  *
251  * \param sub subscription
252  *
253  * \return string description of the subscription
254  */
255 const char *ast_event_subscriber_get_description(struct ast_event_sub *sub);
256
257 /*!
258  * \brief Check if subscribers exist
259  *
260  * \param event_type This is the type of event that the caller would like to
261  *        check for subscribers to.
262  *
263  * The rest of the arguments to this function specify additional parameters for
264  * checking for subscriptions to subsets of an event type. The arguments must
265  * in sets of:
266  * \code
267  *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
268  * \endcode
269  * and must end with AST_EVENT_IE_END.
270  *
271  * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
272  * by a valid IE payload type.  If the payload type specified is
273  * AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided.
274  * Otherwise, a payload must also be specified.
275  *
276  * \return This returns one of the values defined in the ast_event_subscriber_res
277  *         enum which will indicate if subscribers exist that match the given
278  *         criteria.
279  *
280  * Example usage:
281  *
282  * \code
283  * if (ast_event_check_subscriber(AST_EVENT_MWI,
284  *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox,
285  *     AST_EVENT_IE_END) == AST_EVENT_SUB_NONE) {
286  *       return;
287  * }
288  * \endcode
289  *
290  * This example will check if there are any subscribers to MWI events for the
291  * mailbox defined in the "mailbox" variable.
292  */
293 enum ast_event_subscriber_res ast_event_check_subscriber(enum ast_event_type event_type, ...);
294
295 /*!
296  * \brief Report current subscriptions to a subscription subscriber
297  *
298  * \arg sub the subscription subscriber
299  *
300  * \return nothing
301  *
302  * This reports all of the current subscribers to a subscriber of
303  * subscribers to a specific event type.  (Try saying that a few times fast).
304  *
305  * The idea here is that it is sometimes very useful for a module to know when
306  * someone subscribes to events.  However, when they first subscribe, this
307  * provides that module the ability to request the event core report to them
308  * all of the subscriptions to that event type that already exist.
309  */
310 void ast_event_report_subs(const struct ast_event_sub *sub);
311
312 /*!
313  * \brief Dump the event cache for the subscriber
314  * \since 1.6.1
315  */
316 void ast_event_dump_cache(const struct ast_event_sub *event_sub);
317
318 /*!
319  * \brief Create a new event
320  *
321  * \param event_type The type of event to create
322  *
323  * The rest of the arguments to this function specify information elements to
324  * add to the event.  They are specified in the form:
325  * \code
326  *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
327  * \endcode
328  * and must end with AST_EVENT_IE_END.
329  *
330  * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
331  * by a valid IE payload type.  The payload type, EXISTS, should not be used here
332  * because it makes no sense to do so.  So, a payload must also be specified
333  * after the IE payload type.
334  *
335  * \note The EID IE will be appended automatically when this function is used
336  *       with at least one IE specified.
337  *
338  * \return This returns the event that has been created.  If there is an error
339  *         creating the event, NULL will be returned.
340  *
341  * Example usage:
342  *
343  * \code
344  * if (!(event = ast_event_new(AST_EVENT_MWI,
345  *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox,
346  *     AST_EVENT_IE_NEWMSGS, AST_EVENT_IE_PLTYPE_UINT, new,
347  *     AST_EVENT_IE_OLDMSGS, AST_EVENT_IE_PLTYPE_UINT, old,
348  *     AST_EVENT_IE_END))) {
349  *       return;
350  * }
351  * \endcode
352  *
353  * This creates a MWI event with 3 information elements, a mailbox which is
354  * a string, and the number of new and old messages, specified as integers.
355  */
356 struct ast_event *ast_event_new(enum ast_event_type event_type, ...);
357
358 /*!
359  * \brief Destroy an event
360  *
361  * \param event the event to destroy
362  *
363  * \return Nothing
364  *
365  * \note Events that have been queued should *not* be destroyed by the code that
366  *       created the event.  It will be automatically destroyed after being
367  *       dispatched to the appropriate subscribers.
368  */
369 void ast_event_destroy(struct ast_event *event);
370
371 /*!
372  * \brief Queue an event
373  *
374  * \param event the event to be queued
375  *
376  * \retval zero success
377  * \retval non-zero failure.  Note that the caller of this function is
378  *         responsible for destroying the event in the case of a failure.
379  *
380  * This function queues an event to be dispatched to all of the appropriate
381  * subscribers.  This function will not block while the event is being
382  * dispatched because the event is queued up for a dispatching thread 
383  * to handle.
384  */
385 int ast_event_queue(struct ast_event *event);
386
387 /*!
388  * \brief Queue and cache an event
389  *
390  * \param event the event to be queued and cached
391  *
392  * \details
393  * The purpose of caching events is so that the core can retain the last known
394  * information for events that represent some sort of state.  That way, when
395  * code needs to find out the current state, it can query the cache.
396  *
397  * The event API already knows which events can be cached and how to cache them.
398  *
399  * \retval 0 success
400  * \retval non-zero failure.
401  */
402 int ast_event_queue_and_cache(struct ast_event *event);
403
404 /*!
405  * \brief Retrieve an event from the cache
406  *
407  * \param ast_event_type The type of event to retrieve from the cache
408  *
409  * The rest of the arguments to this function specify information elements to
410  * match for retrieving events from the cache.  They are specified in the form:
411  * \code
412  *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
413  * \endcode
414  * and must end with AST_EVENT_IE_END.
415  *
416  * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
417  * by a valid IE payload type.  If the payload type specified is
418  * AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided.
419  * Otherwise, a payload must also be specified.
420  *
421  * \return A reference to an event retrieved from the cache.  If no event was
422  *         found that matches the specified criteria, then NULL will be returned.
423  *
424  * \note If more than one event in the cache matches the specified criteria, only
425  *       one will be returned, and it is undefined which one it will be.
426  *
427  * \note The caller of this function *must* call ast_event_destroy() on the
428  *       returned event after it is done using it.
429  *
430  * Example Usage:
431  *
432  * \code
433  * event = ast_event_get_cached(AST_EVENT_MWI,
434  *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox,
435  *     AST_EVENT_IE_END);
436  * \endcode
437  *
438  * This example will check for an MWI event in the cache that matches the
439  * specified mailbox.  This would be the way to find out the last known state
440  * of a mailbox without having to poll the mailbox directly.
441  */
442 struct ast_event *ast_event_get_cached(enum ast_event_type, ...);
443
444 /*!
445  * \brief Append an information element that has a string 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 str The string 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_str(struct ast_event **event, enum ast_event_ie_type ie_type,
459         const char *str);
460
461 /*!
462  * \brief Append an information element that has an integer 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 The integer for the payload of the IE
467  *
468  * \retval 0 success
469  * \retval -1 failure
470  *
471  * The pointer to the event will get updated with the new location for the event
472  * that now contains the appended information element.  If the re-allocation of
473  * the memory for this event fails, it will be set to NULL.
474  */
475 int ast_event_append_ie_uint(struct ast_event **event, enum ast_event_ie_type ie_type,
476         uint32_t data);
477
478 /*!
479  * \brief Append an information element that has a bitflags payload
480  *
481  * \param event the event that the IE will be appended to
482  * \param ie_type the type of IE to append
483  * \param bitflags the flags that are the payload of the IE
484  *
485  * \retval 0 success
486  * \retval -1 failure
487  * \since 1.8
488  *
489  * The pointer to the event will get updated with the new location for the event
490  * that now contains the appended information element.  If the re-allocation of
491  * the memory for this event fails, it will be set to NULL.
492  */
493 int ast_event_append_ie_bitflags(struct ast_event **event, enum ast_event_ie_type ie_type,
494         uint32_t bitflags);
495
496 /*!
497  * \brief Append an information element that has a raw payload
498  *
499  * \param event the event that the IE will be appended to
500  * \param ie_type the type of IE to append
501  * \param data A pointer to the raw data for the payload of the IE
502  * \param data_len The amount of data to copy into the payload
503  *
504  * \retval 0 success
505  * \retval -1 failure
506  *
507  * The pointer to the event will get updated with the new location for the event
508  * that now contains the appended information element.  If the re-allocation of
509  * the memory for this event fails, it will be set to NULL.
510  */
511 int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_type,
512         const void *data, size_t data_len);
513
514 /*!
515  * \brief Append the global EID IE
516  *
517  * \param event the event to append IE to
518  *
519  * \note For ast_event_new() that includes IEs, this is done automatically
520  *       for you.
521  *
522  * \retval 0 success
523  * \retval -1 failure
524  */
525 int ast_event_append_eid(struct ast_event **event);
526
527 /*!
528  * \brief Get the value of an information element that has an integer payload
529  *
530  * \param event The event to get the IE from
531  * \param ie_type the type of information element to retrieve
532  *
533  * \return This returns the payload of the information element with the given type.
534  *         However, an IE with a payload of 0, and the case where no IE is found
535  *         yield the same return value.
536  */
537 uint32_t ast_event_get_ie_uint(const struct ast_event *event, enum ast_event_ie_type ie_type);
538
539 /*!
540  * \brief Get the value of an information element that has a bitflags payload
541  *
542  * \param event The event to get the IE from
543  * \param ie_type the type of information element to retrieve
544  *
545  * \return This returns the payload of the information element with the given type.
546  *         However, an IE with a payload of 0, and the case where no IE is found
547  *         yield the same return value.
548  */
549 uint32_t ast_event_get_ie_bitflags(const struct ast_event *event, enum ast_event_ie_type ie_type);
550
551 /*!
552  * \brief Get the value of an information element that has a string payload
553  *
554  * \param event The event to get the IE from
555  * \param ie_type the type of information element to retrieve
556  *
557  * \return This returns the payload of the information element with the given type.
558  *         If the information element isn't found, NULL will be returned.
559  */
560 const char *ast_event_get_ie_str(const struct ast_event *event, enum ast_event_ie_type ie_type);
561
562 /*!
563  * \brief Get the hash for the string payload of an IE
564  *
565  * \param event The event to get the IE from
566  * \param ie_type the type of information element to retrieve the hash for
567  *
568  * \return This function returns the hash value as calculated by ast_str_hash()
569  *         for the string payload.  This is stored in the event to avoid
570  *         unnecessary string comparisons.
571  */
572 uint32_t ast_event_get_ie_str_hash(const struct ast_event *event, enum ast_event_ie_type ie_type);
573
574 /*!
575  * \brief Get the value of an information element that has a raw payload
576  *
577  * \param event The event to get the IE from
578  * \param ie_type the type of information element to retrieve
579  *
580  * \return This returns the payload of the information element with the given type.
581  *         If the information element isn't found, NULL will be returned.
582  */
583 const void *ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_ie_type ie_type);
584
585 /*!
586  * \brief Get the length of the raw payload for a particular IE
587  *
588  * \param event The event to get the IE payload length from
589  * \param ie_type the type of information element to get the length of
590  *
591  * \return If an IE of type ie_type is found, its payload length is returned.
592  *         Otherwise, 0 is returned.
593  */
594 uint16_t ast_event_get_ie_raw_payload_len(const struct ast_event *event, enum ast_event_ie_type ie_type);
595
596 /*!
597  * \brief Get the string representation of an information element type
598  *
599  * \param ie_type the information element type to get the string representation of
600  *
601  * \return the string representation of the information element type
602  * \since 1.6.1
603  */
604 const char *ast_event_get_ie_type_name(enum ast_event_ie_type ie_type);
605
606 /*!
607  * \brief Get the payload type for a given information element type
608  *
609  * \param ie_type the information element type to get the payload type of
610  *
611  * \return the payload type for the provided IE type
612  * \since 1.6.1
613  */
614 enum ast_event_ie_pltype ast_event_get_ie_pltype(enum ast_event_ie_type ie_type);
615
616 /*!
617  * \brief Get the type for an event
618  *
619  * \param event the event to get the type for
620  *
621  * \return the event type as represented by one of the values in the
622  *         ast_event_type enum
623  */
624 enum ast_event_type ast_event_get_type(const struct ast_event *event);
625
626 /*!
627  * \brief Get the string representation of the type of the given event
628  *
629  * \arg event the event to get the type of
630  *
631  * \return the string representation of the event type of the provided event
632  * \since 1.6.1
633  */
634 const char *ast_event_get_type_name(const struct ast_event *event);
635
636 /*!
637  * \brief Convert a string into an event type
638  *
639  * \param str the string to convert
640  * \param event_type an output parameter for the event type
641  *
642  * \retval 0 success
643  * \retval non-zero failure
644  * \since 1.6.1
645  */
646 int ast_event_str_to_event_type(const char *str, enum ast_event_type *event_type);
647
648 /*!
649  * \brief Convert a string to an IE type
650  *
651  * \param str the string to convert
652  * \param ie_type an output parameter for the IE type
653  *
654  * \retval 0 success
655  * \retval non-zero failure
656  * \since 1.6.1
657  */
658 int ast_event_str_to_ie_type(const char *str, enum ast_event_ie_type *ie_type);
659
660 /*!
661  * \brief Get the size of an event
662  *
663  * \param event the event to get the size of
664  *
665  * \return the number of bytes contained in the event
666  * \since 1.6.1
667  */
668 size_t ast_event_get_size(const struct ast_event *event);
669
670 /*!
671  * \brief Initialize an event iterator instance
672  *
673  * \param iterator The iterator instance to initialize
674  * \param event The event that will be iterated through
675  *
676  * \retval 0 Success, there are IEs available to iterate
677  * \retval -1 Failure, there are no IEs in the event to iterate
678  */
679 int ast_event_iterator_init(struct ast_event_iterator *iterator, const struct ast_event *event);
680
681 /*!
682  * \brief Move iterator instance to next IE
683  *
684  * \param iterator The iterator instance
685  *
686  * \retval 0 on success
687  * \retval -1 if end is reached
688  */
689 int ast_event_iterator_next(struct ast_event_iterator *iterator);
690
691 /*!
692  * \brief Get the type of the current IE in the iterator instance
693  *
694  * \param iterator The iterator instance
695  *
696  * \return the ie type as represented by one of the value sin the
697  *         ast_event_ie_type enum
698  */
699 enum ast_event_ie_type ast_event_iterator_get_ie_type(struct ast_event_iterator *iterator);
700
701 /*!
702  * \brief Get the value of the current IE in the iterator as an integer payload
703  *
704  * \param iterator The iterator instance
705  *
706  * \return This returns the payload of the information element as a uint.
707  */
708 uint32_t ast_event_iterator_get_ie_uint(struct ast_event_iterator *iterator);
709
710 /*!
711  * \brief Get the value of the current IE in the iterator as a bitflags payload
712  *
713  * \param iterator The iterator instance
714  *
715  * \return This returns the payload of the information element as bitflags.
716  */
717 uint32_t ast_event_iterator_get_ie_bitflags(struct ast_event_iterator *iterator);
718
719 /*!
720  * \brief Get the value of the current IE in the iterator as a string payload
721  *
722  * \param iterator The iterator instance
723  *
724  * \return This returns the payload of the information element as a string.
725  */
726 const char *ast_event_iterator_get_ie_str(struct ast_event_iterator *iterator);
727
728 /*!
729  * \brief Get the value of the current IE in the iterator instance that has a raw payload
730  *
731  * \param iterator The iterator instance
732  *
733  * \return This returns the payload of the information element as type raw.
734  */
735 void *ast_event_iterator_get_ie_raw(struct ast_event_iterator *iterator);
736
737 /*!
738  * \brief Get the length of the raw payload for the current IE for an iterator
739  *
740  * \param iterator The IE iterator
741  *
742  * \return The payload length of the current IE
743  */
744 uint16_t ast_event_iterator_get_ie_raw_payload_len(struct ast_event_iterator *iterator);
745
746 /*!
747  * \brief Get the minimum length of an ast_event.
748  *
749  * \return minimum amount of memory that will be consumed by any ast_event.
750  */
751 size_t ast_event_minimum_length(void);
752
753 #if defined(__cplusplus) || defined(c_plusplus)
754 }
755 #endif
756
757 #endif /* AST_EVENT_H */