Wed Jan 8 2020 09:49:47

Asterisk developer's documentation


event.h
Go to the documentation of this file.
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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 */
int ast_event_sub_append_ie_str(struct ast_event_sub *sub, enum ast_event_ie_type ie_type, const char *str)
Append a string parameter to a subscription.
Definition: event.c:826
An event.
Definition: event.c:85
int ast_event_str_to_ie_type(const char *str, enum ast_event_ie_type *ie_type)
Convert a string to an IE type.
Definition: event.c:324
int ast_event_sub_append_ie_bitflags(struct ast_event_sub *sub, enum ast_event_ie_type ie_type, uint32_t flags)
Append a bitflags parameter to a subscription.
Definition: event.c:783
int ast_event_str_to_event_type(const char *str, enum ast_event_type *event_type)
Convert a string into an event type.
Definition: event.c:288
uint32_t ast_event_get_ie_bitflags(const struct ast_event *event, enum ast_event_ie_type ie_type)
Get the value of an information element that has a bitflags payload.
Definition: event.c:1084
enum ast_event_type ast_event_get_type(const struct ast_event *event)
Get the type for an event.
Definition: event.c:1070
ast_event_ie_pltype
Payload types for event information elements.
Definition: event_defs.h:299
enum ast_event_subscriber_res ast_event_check_subscriber(enum ast_event_type event_type,...)
Check if subscribers exist.
Definition: event.c:448
int ast_event_queue_and_cache(struct ast_event *event)
Queue and cache an event.
Definition: event.c:1465
void ast_event_report_subs(const struct ast_event_sub *sub)
Report current subscriptions to a subscription subscriber.
Definition: event.c:701
struct ast_event_sub * event_sub
Definition: devicestate.c:201
ast_event_subscriber_res
Results for checking for subscribers.
Definition: event_defs.h:318
const char * ast_event_subscriber_get_description(struct ast_event_sub *sub)
Get description for a subscription.
Definition: event.c:982
struct ast_event * ast_event_get_cached(enum ast_event_type,...)
Retrieve an event from the cache.
Definition: event.c:1342
int ast_event_append_ie_bitflags(struct ast_event **event, enum ast_event_ie_type ie_type, uint32_t bitflags)
Append an information element that has a bitflags payload.
Definition: event.c:1167
uint32_t ast_event_iterator_get_ie_bitflags(struct ast_event_iterator *iterator)
Get the value of the current IE in the iterator as a bitflags payload.
Definition: event.c:1046
enum ast_event_ie_pltype ast_event_get_ie_pltype(enum ast_event_ie_type ie_type)
Get the payload type for a given information element type.
Definition: event.c:314
const char * str
Definition: app_jack.c:144
supposed to be an opaque type
Definition: event_defs.h:335
void ast_event_sub_destroy(struct ast_event_sub *sub)
Destroy an allocated subscription.
Definition: event.c:971
uint32_t ast_event_get_ie_str_hash(const struct ast_event *event, enum ast_event_ie_type ie_type)
Get the hash for the string payload of an IE.
Definition: event.c:1093
int ast_event_queue(struct ast_event *event)
Queue an event.
Definition: event.c:1517
ast_event_ie_type
Event Information Element types.
Definition: event_defs.h:62
ast_event_type
Event types.
Definition: event_defs.h:30
void(* ast_event_cb_t)(const struct ast_event *event, void *userdata)
Subscriber event callback type.
Definition: event.h:74
void * userdata
Definition: event.c:128
Generic event system.
int ast_event_sub_append_ie_raw(struct ast_event_sub *sub, enum ast_event_ie_type ie_type, void *data, size_t raw_datalen)
Append a raw parameter to a subscription.
Definition: event.c:860
const void * ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_ie_type ie_type)
Get the value of an information element that has a raw payload.
Definition: event.c:1111
void ast_event_dump_cache(const struct ast_event_sub *event_sub)
Dump the event cache for the subscriber.
Definition: event.c:654
int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_type, const void *data, size_t data_len)
Append an information element that has a raw payload.
Definition: event.c:1174
ast_event_cb_t cb
Definition: event.c:126
Event subscription.
Definition: event.c:124
int ast_event_sub_activate(struct ast_event_sub *sub)
Activate a dynamically built subscription.
Definition: event.c:889
int ast_event_append_ie_str(struct ast_event **event, enum ast_event_ie_type ie_type, const char *str)
Append an information element that has a string payload.
Definition: event.c:1139
size_t ast_event_minimum_length(void)
Get the minimum length of an ast_event.
Definition: event.c:1854
int ast_event_sub_append_ie_uint(struct ast_event_sub *sub, enum ast_event_ie_type ie_type, uint32_t uint)
Append a uint parameter to a subscription.
Definition: event.c:761
char description[64]
Definition: event.c:127
static const char type[]
Definition: chan_nbs.c:57
uint32_t ast_event_get_ie_uint(const struct ast_event *event, enum ast_event_ie_type ie_type)
Get the value of an information element that has an integer payload.
Definition: event.c:1075
int ast_event_iterator_init(struct ast_event_iterator *iterator, const struct ast_event *event)
Initialize an event iterator instance.
Definition: event.c:1014
void ast_event_destroy(struct ast_event *event)
Destroy an event.
Definition: event.c:1314
int ast_event_iterator_next(struct ast_event_iterator *iterator)
Move iterator instance to next IE.
Definition: event.c:1030
struct ast_event * ast_event_new(enum ast_event_type event_type,...)
Create a new event.
Definition: event.c:1202
struct ast_event_sub * ast_event_subscribe(enum ast_event_type event_type, ast_event_cb_t cb, const char *description, void *userdata,...)
Subscribe to events.
Definition: event.c:909
uint32_t ast_event_iterator_get_ie_uint(struct ast_event_iterator *iterator)
Get the value of the current IE in the iterator as an integer payload.
Definition: event.c:1041
int ast_event_append_eid(struct ast_event **event)
Append the global EID IE.
Definition: event.c:1308
uint16_t ast_event_iterator_get_ie_raw_payload_len(struct ast_event_iterator *iterator)
Get the length of the raw payload for the current IE for an iterator.
Definition: event.c:1065
const char * ast_event_get_ie_type_name(enum ast_event_ie_type ie_type)
Get the string representation of an information element type.
Definition: event.c:304
const char * ast_event_iterator_get_ie_str(struct ast_event_iterator *iterator)
Get the value of the current IE in the iterator as a string payload.
Definition: event.c:1051
size_t ast_event_get_size(const struct ast_event *event)
Get the size of an event.
Definition: event.c:340
const char * ast_event_get_type_name(const struct ast_event *event)
Get the string representation of the type of the given event.
Definition: event.c:274
const char * ast_event_get_ie_str(const struct ast_event *event, enum ast_event_ie_type ie_type)
Get the value of an information element that has a string payload.
Definition: event.c:1102
void * ast_event_iterator_get_ie_raw(struct ast_event_iterator *iterator)
Get the value of the current IE in the iterator instance that has a raw payload.
Definition: event.c:1060
enum ast_event_ie_type ast_event_iterator_get_ie_type(struct ast_event_iterator *iterator)
Get the type of the current IE in the iterator instance.
Definition: event.c:1036
struct ast_event_sub * ast_event_unsubscribe(struct ast_event_sub *event_sub)
Un-subscribe from events.
Definition: event.c:987
struct ast_event_sub * ast_event_subscribe_new(enum ast_event_type type, ast_event_cb_t cb, void *userdata)
Allocate a subscription, but do not activate it.
Definition: event.c:739
uint16_t ast_event_get_ie_raw_payload_len(const struct ast_event *event, enum ast_event_ie_type ie_type)
Get the length of the raw payload for a particular IE.
Definition: event.c:1125
int ast_event_append_ie_uint(struct ast_event **event, enum ast_event_ie_type ie_type, uint32_t data)
Append an information element that has an integer payload.
Definition: event.c:1160
int ast_event_sub_append_ie_exists(struct ast_event_sub *sub, enum ast_event_ie_type ie_type)
Append an &#39;exists&#39; parameter to a subscription.
Definition: event.c:805