00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 2007 - 2008, Digium, Inc. 00005 * 00006 * Russell Bryant <russell@digium.com> 00007 * 00008 * See http://www.asterisk.org for more information about 00009 * the Asterisk project. Please do not directly contact 00010 * any of the maintainers of this project for assistance; 00011 * the project provides a web site, mailing lists and IRC 00012 * channels for your use. 00013 * 00014 * This program is free software, distributed under the terms of 00015 * the GNU General Public License Version 2. See the LICENSE file 00016 * at the top of the source tree. 00017 */ 00018 00019 /*! 00020 * \file 00021 * \author Russell Bryant <russell@digium.com> 00022 * \ref AstGenericEvents 00023 */ 00024 00025 /*! 00026 * \page AstGenericEvents Generic event system 00027 * 00028 * The purpose of this API is to provide a generic way to share events between 00029 * Asterisk modules. Code can generate events, and other code can subscribe to 00030 * them. 00031 * 00032 * Events have an associated event type, as well as information elements. The 00033 * information elements are the meta data that go along with each event. For 00034 * example, in the case of message waiting indication, the event type is MWI, 00035 * and each MWI event contains at least three information elements: the 00036 * mailbox, the number of new messages, and the number of old messages. 00037 * 00038 * Subscriptions to events consist of an event type and information elements, 00039 * as well. Subscriptions can be to all events, or a certain subset of events. 00040 * If an event type is provided, only events of that type will be sent to this 00041 * subscriber. Furthermore, if information elements are supplied with the 00042 * subscription, only events that contain the specified information elements 00043 * with specified values will be sent to the subscriber. For example, when a 00044 * SIP phone subscribes to MWI for mailbox 1234, then chan_sip can subscribe 00045 * to internal Asterisk MWI events with the MAILBOX information element with 00046 * a value of "1234". 00047 * 00048 * Another key feature of this event system is the ability to cache events. 00049 * It is useful for some types of events to be able to remember the last known 00050 * value. These are usually events that indicate some kind of state change. 00051 * In the example of MWI, app_voicemail can instruct the event core to cache 00052 * these events based on the mailbox. So, the last known MWI state of each 00053 * mailbox will be cached, and other modules can retrieve this information 00054 * on demand without having to poll the mailbox directly. 00055 */ 00056 00057 #ifndef AST_EVENT_H 00058 #define AST_EVENT_H 00059 00060 #if defined(__cplusplus) || defined(c_plusplus) 00061 extern "C" { 00062 #endif 00063 00064 #include "asterisk/event_defs.h" 00065 00066 /*! 00067 * \brief Subscriber event callback type 00068 * 00069 * \param event the event being passed to the subscriber 00070 * \param userdata the data provider in the call to ast_event_subscribe() 00071 * 00072 * \return The event callbacks do not return anything. 00073 */ 00074 typedef void (*ast_event_cb_t)(const struct ast_event *event, void *userdata); 00075 00076 /*! 00077 * \brief Subscribe to events 00078 * 00079 * \param event_type The type of events to subscribe to 00080 * \param cb The function to be called with events 00081 * \param userdata data to be passed to the event callback 00082 * 00083 * The rest of the arguments to this function specify additional parameters for 00084 * the subscription to filter which events are passed to this subscriber. The 00085 * arguments must be in sets of: 00086 * \code 00087 * <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ] 00088 * \endcode 00089 * and must end with AST_EVENT_IE_END. 00090 * 00091 * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed 00092 * by a valid IE payload type. If the payload type specified is 00093 * AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided. 00094 * Otherwise, a payload must also be specified. 00095 * 00096 * \return This returns a reference to the subscription for use with 00097 * un-subscribing later. If there is a failure in creating the 00098 * subscription, NULL will be returned. 00099 * 00100 * Example usage: 00101 * 00102 * \code 00103 * peer->mwi_event_sub = ast_event_subscribe(AST_EVENT_MWI, mwi_event_cb, peer, 00104 * AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, peer->mailbox, 00105 * AST_EVENT_IE_END); 00106 * \endcode 00107 * 00108 * This creates a subscription to AST_EVENT_MWI events that contain an 00109 * information element, AST_EVENT_IE_MAILBOX, with the same string value 00110 * contained in peer->mailbox. Also, the event callback will be passed a 00111 * pointer to the peer. 00112 */ 00113 struct ast_event_sub *ast_event_subscribe(enum ast_event_type event_type, 00114 ast_event_cb_t cb, void *userdata, ...); 00115 00116 /*! 00117 * \brief Allocate a subscription, but do not activate it 00118 * 00119 * \param type the event type to subscribe to 00120 * \param cb the function to call when an event matches this subscription 00121 * \param userdata data to pass to the provided callback 00122 * 00123 * This function should be used when you want to dynamically build a 00124 * subscription. 00125 * 00126 * \return the allocated subscription, or NULL on failure 00127 * \since 1.6.1 00128 */ 00129 struct ast_event_sub *ast_event_subscribe_new(enum ast_event_type type, 00130 ast_event_cb_t cb, void *userdata); 00131 00132 /*! 00133 * \brief Destroy an allocated subscription 00134 * 00135 * \param sub the subscription to destroy 00136 * 00137 * This function should be used when a subscription is allocated with 00138 * ast_event_subscribe_new(), but for some reason, you want to destroy it 00139 * instead of activating it. This could be because of an error when 00140 * reading in the configuration for the dynamically built subscription. 00141 * \since 1.6.1 00142 */ 00143 void ast_event_sub_destroy(struct ast_event_sub *sub); 00144 00145 /*! 00146 * \brief Append a uint parameter to a subscription 00147 * 00148 * \param sub the dynamic subscription allocated with ast_event_subscribe_new() 00149 * \param ie_type the information element type for the parameter 00150 * \param uint the value that must be present in the event to match this subscription 00151 * 00152 * \retval 0 success 00153 * \retval non-zero failure 00154 * \since 1.6.1 00155 */ 00156 int ast_event_sub_append_ie_uint(struct ast_event_sub *sub, 00157 enum ast_event_ie_type ie_type, uint32_t uint); 00158 00159 /*! 00160 * \brief Append a string parameter to a subscription 00161 * 00162 * \param sub the dynamic subscription allocated with ast_event_subscribe_new() 00163 * \param ie_type the information element type for the parameter 00164 * \param str the string that must be present in the event to match this subscription 00165 * 00166 * \retval 0 success 00167 * \retval non-zero failure 00168 * \since 1.6.1 00169 */ 00170 int ast_event_sub_append_ie_str(struct ast_event_sub *sub, 00171 enum ast_event_ie_type ie_type, const char *str); 00172 00173 /*! 00174 * \brief Append a raw parameter to a subscription 00175 * 00176 * \param sub the dynamic subscription allocated with ast_event_subscribe_new() 00177 * \param ie_type the information element type for the parameter 00178 * \param raw the data that must be present in the event to match this subscription 00179 * 00180 * \retval 0 success 00181 * \retval non-zero failure 00182 * \since 1.6.1 00183 */ 00184 int ast_event_sub_append_ie_raw(struct ast_event_sub *sub, 00185 enum ast_event_ie_type ie_type, void *data, size_t raw_datalen); 00186 00187 /*! 00188 * \brief Append an 'exists' parameter to a subscription 00189 * 00190 * \param sub the dynamic subscription allocated with ast_event_subscribe_new() 00191 * \param ie_type the information element type that must be present in the event 00192 * for it to match this subscription. 00193 * 00194 * \retval 0 success 00195 * \retval non-zero failure 00196 * \since 1.6.1 00197 */ 00198 int ast_event_sub_append_ie_exists(struct ast_event_sub *sub, 00199 enum ast_event_ie_type ie_type); 00200 00201 /*! 00202 * \brief Activate a dynamically built subscription 00203 * 00204 * \param sub the subscription to activate that was allocated using 00205 * ast_event_subscribe_new() 00206 * 00207 * Once a dynamically built subscription has had all of the parameters added 00208 * to it, it should be activated using this function. 00209 * 00210 * \retval 0 success 00211 * \retval non-zero failure 00212 * \since 1.6.1 00213 */ 00214 int ast_event_sub_activate(struct ast_event_sub *sub); 00215 00216 /*! 00217 * \brief Un-subscribe from events 00218 * 00219 * \param event_sub This is the reference to the subscription returned by 00220 * ast_event_subscribe. 00221 * 00222 * This function will remove a subscription and free the associated data 00223 * structures. 00224 * 00225 * \return NULL for convenience. 00226 * \version 1.6.1 return changed to NULL 00227 */ 00228 struct ast_event_sub *ast_event_unsubscribe(struct ast_event_sub *event_sub); 00229 00230 /*! 00231 * \brief Check if subscribers exist 00232 * 00233 * \param event_type This is the type of event that the caller would like to 00234 * check for subscribers to. 00235 * 00236 * The rest of the arguments to this function specify additional parameters for 00237 * checking for subscriptions to subsets of an event type. The arguments must 00238 * in sets of: 00239 * \code 00240 * <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ] 00241 * \endcode 00242 * and must end with AST_EVENT_IE_END. 00243 * 00244 * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed 00245 * by a valid IE payload type. If the payload type specified is 00246 * AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided. 00247 * Otherwise, a payload must also be specified. 00248 * 00249 * \return This returns one of the values defined in the ast_event_subscriber_res 00250 * enum which will indicate if subscribers exist that match the given 00251 * criteria. 00252 * 00253 * Example usage: 00254 * 00255 * \code 00256 * if (ast_event_check_subscriber(AST_EVENT_MWI, 00257 * AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox, 00258 * AST_EVENT_IE_END) == AST_EVENT_SUB_NONE) { 00259 * return; 00260 * } 00261 * \endcode 00262 * 00263 * This example will check if there are any subscribers to MWI events for the 00264 * mailbox defined in the "mailbox" variable. 00265 */ 00266 enum ast_event_subscriber_res ast_event_check_subscriber(enum ast_event_type event_type, ...); 00267 00268 /*! 00269 * \brief Report current subscriptions to a subscription subscriber 00270 * 00271 * \arg sub the subscription subscriber 00272 * 00273 * \return nothing 00274 * 00275 * This reports all of the current subscribers to a subscriber of 00276 * subscribers to a specific event type. (Try saying that a few times fast). 00277 * 00278 * The idea here is that it is sometimes very useful for a module to know when 00279 * someone subscribes to events. However, when they first subscribe, this 00280 * provides that module the ability to request the event core report to them 00281 * all of the subscriptions to that event type that already exist. 00282 */ 00283 void ast_event_report_subs(const struct ast_event_sub *sub); 00284 00285 /*! 00286 * \brief Dump the event cache for the subscriber 00287 * \since 1.6.1 00288 */ 00289 void ast_event_dump_cache(const struct ast_event_sub *event_sub); 00290 00291 /*! 00292 * \brief Create a new event 00293 * 00294 * \param event_type The type of event to create 00295 * 00296 * The rest of the arguments to this function specify information elements to 00297 * add to the event. They are specified in the form: 00298 * \code 00299 * <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ] 00300 * \endcode 00301 * and must end with AST_EVENT_IE_END. 00302 * 00303 * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed 00304 * by a valid IE payload type. The payload type, EXISTS, should not be used here 00305 * because it makes no sense to do so. So, a payload must also be specified 00306 * after the IE payload type. 00307 * 00308 * \return This returns the event that has been created. If there is an error 00309 * creating the event, NULL will be returned. 00310 * 00311 * Example usage: 00312 * 00313 * \code 00314 * if (!(event = ast_event_new(AST_EVENT_MWI, 00315 * AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox, 00316 * AST_EVENT_IE_NEWMSGS, AST_EVENT_IE_PLTYPE_UINT, new, 00317 * AST_EVENT_IE_OLDMSGS, AST_EVENT_IE_PLTYPE_UINT, old, 00318 * AST_EVENT_IE_END))) { 00319 * return; 00320 * } 00321 * \endcode 00322 * 00323 * This creates a MWI event with 3 information elements, a mailbox which is 00324 * a string, and the number of new and old messages, specified as integers. 00325 */ 00326 struct ast_event *ast_event_new(enum ast_event_type event_type, ...); 00327 00328 /*! 00329 * \brief Destroy an event 00330 * 00331 * \param event the event to destroy 00332 * 00333 * \return Nothing 00334 * 00335 * \note Events that have been queued should *not* be destroyed by the code that 00336 * created the event. It will be automatically destroyed after being 00337 * dispatched to the appropriate subscribers. 00338 */ 00339 void ast_event_destroy(struct ast_event *event); 00340 00341 /*! 00342 * \brief Queue an event 00343 * 00344 * \param event the event to be queued 00345 * 00346 * \retval zero success 00347 * \retval non-zero failure 00348 * 00349 * This function queues an event to be dispatched to all of the appropriate 00350 * subscribers. This function will not block while the event is being 00351 * dispatched because a pool of event dispatching threads handle the event 00352 * queue. 00353 */ 00354 int ast_event_queue(struct ast_event *event); 00355 00356 /*! 00357 * \brief Queue and cache an event 00358 * 00359 * \param event the event to be queued and cached 00360 * 00361 * \details 00362 * The purpose of caching events is so that the core can retain the last known 00363 * information for events that represent some sort of state. That way, when 00364 * code needs to find out the current state, it can query the cache. 00365 * 00366 * The event API already knows which events can be cached and how to cache them. 00367 * 00368 * \retval 0 success 00369 * \retval non-zero failure. If failure is returned, the event must be destroyed 00370 * by the caller of this function. 00371 */ 00372 int ast_event_queue_and_cache(struct ast_event *event); 00373 00374 /*! 00375 * \brief Retrieve an event from the cache 00376 * 00377 * \param ast_event_type The type of event to retrieve from the cache 00378 * 00379 * The rest of the arguments to this function specify information elements to 00380 * match for retrieving events from the cache. They are specified in the form: 00381 * \code 00382 * <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ] 00383 * \endcode 00384 * and must end with AST_EVENT_IE_END. 00385 * 00386 * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed 00387 * by a valid IE payload type. If the payload type specified is 00388 * AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided. 00389 * Otherwise, a payload must also be specified. 00390 * 00391 * \return A reference to an event retrieved from the cache. If no event was 00392 * found that matches the specified criteria, then NULL will be returned. 00393 * 00394 * \note If more than one event in the cache matches the specified criteria, only 00395 * one will be returned, and it is undefined which one it will be. 00396 * 00397 * \note The caller of this function *must* call ast_event_destroy() on the 00398 * returned event after it is done using it. 00399 * 00400 * Example Usage: 00401 * 00402 * \code 00403 * event = ast_event_get_cached(AST_EVENT_MWI, 00404 * AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox, 00405 * AST_EVENT_IE_END); 00406 * \endcode 00407 * 00408 * This example will check for an MWI event in the cache that matches the 00409 * specified mailbox. This would be the way to find out the last known state 00410 * of a mailbox without having to poll the mailbox directly. 00411 */ 00412 struct ast_event *ast_event_get_cached(enum ast_event_type, ...); 00413 00414 /*! 00415 * \brief Append an information element that has a string payload 00416 * 00417 * \param event the event that the IE will be appended to 00418 * \param ie_type the type of IE to append 00419 * \param str The string for the payload of the IE 00420 * 00421 * \retval 0 success 00422 * \retval -1 failure 00423 * 00424 * The pointer to the event will get updated with the new location for the event 00425 * that now contains the appended information element. If the re-allocation of 00426 * the memory for this event fails, it will be set to NULL. 00427 */ 00428 int ast_event_append_ie_str(struct ast_event **event, enum ast_event_ie_type ie_type, 00429 const char *str); 00430 00431 /*! 00432 * \brief Append an information element that has an integer payload 00433 * 00434 * \param event the event that the IE will be appended to 00435 * \param ie_type the type of IE to append 00436 * \param data The integer for the payload of the IE 00437 * 00438 * \retval 0 success 00439 * \retval -1 failure 00440 * 00441 * The pointer to the event will get updated with the new location for the event 00442 * that now contains the appended information element. If the re-allocation of 00443 * the memory for this event fails, it will be set to NULL. 00444 */ 00445 int ast_event_append_ie_uint(struct ast_event **event, enum ast_event_ie_type ie_type, 00446 uint32_t data); 00447 00448 /*! 00449 * \brief Append an information element that has a raw payload 00450 * 00451 * \param event the event that the IE will be appended to 00452 * \param ie_type the type of IE to append 00453 * \param data A pointer to the raw data for the payload of the IE 00454 * \param data_len The amount of data to copy into the payload 00455 * 00456 * \retval 0 success 00457 * \retval -1 failure 00458 * 00459 * The pointer to the event will get updated with the new location for the event 00460 * that now contains the appended information element. If the re-allocation of 00461 * the memory for this event fails, it will be set to NULL. 00462 */ 00463 int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_type, 00464 const void *data, size_t data_len); 00465 00466 /*! 00467 * \brief Get the value of an information element that has an integer payload 00468 * 00469 * \param event The event to get the IE from 00470 * \param ie_type the type of information element to retrieve 00471 * 00472 * \return This returns the payload of the information element with the given type. 00473 * However, an IE with a payload of 0, and the case where no IE is found 00474 * yield the same return value. 00475 */ 00476 uint32_t ast_event_get_ie_uint(const struct ast_event *event, enum ast_event_ie_type ie_type); 00477 00478 /*! 00479 * \brief Get the value of an information element that has a string payload 00480 * 00481 * \param event The event to get the IE from 00482 * \param ie_type the type of information element to retrieve 00483 * 00484 * \return This returns the payload of the information element with the given type. 00485 * If the information element isn't found, NULL will be returned. 00486 */ 00487 const char *ast_event_get_ie_str(const struct ast_event *event, enum ast_event_ie_type ie_type); 00488 00489 /*! 00490 * \brief Get the hash for the string payload of an IE 00491 * 00492 * \param event The event to get the IE from 00493 * \param ie_type the type of information element to retrieve the hash for 00494 * 00495 * \return This function returns the hash value as calculated by ast_str_hash() 00496 * for the string payload. This is stored in the event to avoid 00497 * unnecessary string comparisons. 00498 */ 00499 uint32_t ast_event_get_ie_str_hash(const struct ast_event *event, enum ast_event_ie_type ie_type); 00500 00501 /*! 00502 * \brief Get the value of an information element that has a raw payload 00503 * 00504 * \param event The event to get the IE from 00505 * \param ie_type the type of information element to retrieve 00506 * 00507 * \return This returns the payload of the information element with the given type. 00508 * If the information element isn't found, NULL will be returned. 00509 */ 00510 const void *ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_ie_type ie_type); 00511 00512 /*! 00513 * \brief Get the string representation of an information element type 00514 * 00515 * \param ie_type the information element type to get the string representation of 00516 * 00517 * \return the string representation of the information element type 00518 * \since 1.6.1 00519 */ 00520 const char *ast_event_get_ie_type_name(enum ast_event_ie_type ie_type); 00521 00522 /*! 00523 * \brief Get the payload type for a given information element type 00524 * 00525 * \param ie_type the information element type to get the payload type of 00526 * 00527 * \return the payload type for the provided IE type 00528 * \since 1.6.1 00529 */ 00530 enum ast_event_ie_pltype ast_event_get_ie_pltype(enum ast_event_ie_type ie_type); 00531 00532 /*! 00533 * \brief Get the type for an event 00534 * 00535 * \param event the event to get the type for 00536 * 00537 * \return the event type as represented by one of the values in the 00538 * ast_event_type enum 00539 */ 00540 enum ast_event_type ast_event_get_type(const struct ast_event *event); 00541 00542 /*! 00543 * \brief Get the string representation of the type of the given event 00544 * 00545 * \arg event the event to get the type of 00546 * 00547 * \return the string representation of the event type of the provided event 00548 * \since 1.6.1 00549 */ 00550 const char *ast_event_get_type_name(const struct ast_event *event); 00551 00552 /*! 00553 * \brief Convert a string into an event type 00554 * 00555 * \param str the string to convert 00556 * \param event_type an output parameter for the event type 00557 * 00558 * \retval 0 success 00559 * \retval non-zero failure 00560 * \since 1.6.1 00561 */ 00562 int ast_event_str_to_event_type(const char *str, enum ast_event_type *event_type); 00563 00564 /*! 00565 * \brief Convert a string to an IE type 00566 * 00567 * \param str the string to convert 00568 * \param ie_type an output parameter for the IE type 00569 * 00570 * \retval 0 success 00571 * \retval non-zero failure 00572 * \since 1.6.1 00573 */ 00574 int ast_event_str_to_ie_type(const char *str, enum ast_event_ie_type *ie_type); 00575 00576 /*! 00577 * \brief Get the size of an event 00578 * 00579 * \param event the event to get the size of 00580 * 00581 * \return the number of bytes contained in the event 00582 * \since 1.6.1 00583 */ 00584 size_t ast_event_get_size(const struct ast_event *event); 00585 00586 /*! 00587 * \brief Initialize an event iterator instance 00588 * 00589 * \param iterator The iterator instance to initialize 00590 * \param event The event that will be iterated through 00591 * 00592 * \return Nothing 00593 */ 00594 void ast_event_iterator_init(struct ast_event_iterator *iterator, const struct ast_event *event); 00595 00596 /*! 00597 * \brief Move iterator instance to next IE 00598 * 00599 * \param iterator The iterator instance 00600 * 00601 * \retval 0 on success 00602 * \retval -1 if end is reached 00603 */ 00604 int ast_event_iterator_next(struct ast_event_iterator *iterator); 00605 00606 /*! 00607 * \brief Get the type of the current IE in the iterator instance 00608 * 00609 * \param iterator The iterator instance 00610 * 00611 * \return the ie type as represented by one of the value sin the 00612 * ast_event_ie_type enum 00613 */ 00614 enum ast_event_ie_type ast_event_iterator_get_ie_type(struct ast_event_iterator *iterator); 00615 00616 /*! 00617 * \brief Get the value of the current IE in the ierator as an integer payload 00618 * 00619 * \param iterator The iterator instance 00620 * 00621 * \return This returns the payload of the information element as a uint. 00622 */ 00623 uint32_t ast_event_iterator_get_ie_uint(struct ast_event_iterator *iterator); 00624 00625 /*! 00626 * \brief Get the value of the current IE in the iterator as a string payload 00627 * 00628 * \param iterator The iterator instance 00629 * 00630 * \return This returns the payload of the information element as a string. 00631 */ 00632 const char *ast_event_iterator_get_ie_str(struct ast_event_iterator *iterator); 00633 00634 /*! 00635 * \brief Get the value of the current IE in the iterator instance that has a raw payload 00636 * 00637 * \param iterator The iterator instance 00638 * 00639 * \return This returns the payload of the information element as type raw. 00640 */ 00641 void *ast_event_iterator_get_ie_raw(struct ast_event_iterator *iterator); 00642 00643 #if defined(__cplusplus) || defined(c_plusplus) 00644 } 00645 #endif 00646 00647 #endif /* AST_EVENT_H */