2 * Asterisk -- An open source telephony toolkit.
4 * Copyright (C) 2007, Digium, Inc.
6 * Russell Bryant <russell@digium.com>
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.
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.
21 * \author Russell Bryant <russell@digium.com>
22 * \brief Generic event system
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
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.
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
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.
56 #include "asterisk/event_defs.h"
59 * \brief Subscriber event callback type
61 * \param event the event being passed to the subscriber
62 * \param userdata the data provider in the call to ast_event_subscribe()
64 * \return The event callbacks do not return anything.
66 typedef void (*ast_event_cb_t)(const struct ast_event *event, void *userdata);
69 * \brief Subscribe to events
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
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:
79 * <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
81 * and must end with AST_EVENT_IE_END.
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.
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.
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,
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.
105 struct ast_event_sub *ast_event_subscribe(enum ast_event_type event_type,
106 ast_event_cb_t cb, void *userdata, ...);
109 * \brief Un-subscribe from events
111 * \param event_sub This is the reference to the subscription returned by
112 * ast_event_subscribe.
116 void ast_event_unsubscribe(struct ast_event_sub *event_sub);
119 * \brief Check if subscribers exist
121 * \param event_type This is the type of event that the caller would like to
122 * check for subscribers to.
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
128 * <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
130 * and must end with AST_EVENT_IE_END.
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.
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
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) {
151 * This example will check if there are any subscribers to MWI events for the
152 * mailbox defined in the "mailbox" variable.
154 enum ast_event_subscriber_res ast_event_check_subscriber(enum ast_event_type event_type, ...);
157 * \brief Report current subscriptions to a subscription subscriber
159 * \arg sub the subscription subscriber
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).
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.
171 void ast_event_report_subs(const struct ast_event_sub *sub);
174 * \brief Create a new event
176 * \param event_type The type of event to create
178 * The rest of the arguments to this function specify information elements to
179 * add to the event. They are specified in the form:
181 * <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
183 * and must end with AST_EVENT_IE_END.
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.
190 * \return This returns the event that has been created. If there is an error
191 * creating the event, NULL will be returned.
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))) {
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.
208 struct ast_event *ast_event_new(enum ast_event_type event_type, ...);
211 * \brief Destroy an event
213 * \param event the event to destroy
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.
221 void ast_event_destroy(struct ast_event *event);
224 * \brief Queue an event
226 * \param event the event to be queued
228 * \retval zero success
229 * \retval non-zero failure
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
236 int ast_event_queue(struct ast_event *event);
239 * \brief Queue and cache an event
241 * \param event the event to be queued and cached
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
250 * <enum ast_event_ie_type>, [enum ast_event_ie_pltype]
252 * and must end with AST_EVENT_IE_END.
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.
260 * \note If more than one IE parameter is specified, they *all* must match for
261 * the event to be removed from the cache.
266 * ast_event_queue_and_cache(event,
267 * AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR,
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.
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.
278 int ast_event_queue_and_cache(struct ast_event *event, ...);
281 * \brief Retrieve an event from the cache
283 * \param ast_event_type The type of event to retrieve from the cache
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:
288 * <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
290 * and must end with AST_EVENT_IE_END.
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.
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.
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.
303 * \note The caller of this function *must* call ast_event_destroy() on the
304 * returned event after it is done using it.
309 * event = ast_event_get_cached(AST_EVENT_MWI,
310 * AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox,
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.
318 struct ast_event *ast_event_get_cached(enum ast_event_type, ...);
321 * \brief Append an information element that has a string payload
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
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.
334 int ast_event_append_ie_str(struct ast_event **event, enum ast_event_ie_type ie_type,
338 * \brief Append an information element that has an integer payload
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
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.
351 int ast_event_append_ie_uint(struct ast_event **event, enum ast_event_ie_type ie_type,
355 * \brief Append an information element that has a raw payload
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
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.
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);
373 * \brief Get the value of an information element that has an integer payload
375 * \param event The event to get the IE from
376 * \param ie_type the type of information element to retrieve
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.
382 uint32_t ast_event_get_ie_uint(const struct ast_event *event, enum ast_event_ie_type ie_type);
385 * \brief Get the value of an information element that has a string payload
387 * \param event The event to get the IE from
388 * \param ie_type the type of information element to retrieve
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.
393 const char *ast_event_get_ie_str(const struct ast_event *event, enum ast_event_ie_type ie_type);
396 * \brief Get the value of an information element that has a raw payload
398 * \param event The event to get the IE from
399 * \param ie_type the type of information element to retrieve
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.
404 const void *ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_ie_type ie_type);
407 * \brief Get the type for an event
409 * \param event the event to get the type for
411 * \return the event type as represented by one of the values in the
412 * ast_event_type enum
414 enum ast_event_type ast_event_get_type(const struct ast_event *event);
416 #endif /* AST_EVENT_H */