00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 2007, 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 Un-subscribe from events 00118 * 00119 * \param event_sub This is the reference to the subscription returned by 00120 * ast_event_subscribe. 00121 * 00122 * \return Nothing 00123 */ 00124 void ast_event_unsubscribe(struct ast_event_sub *event_sub); 00125 00126 /*! 00127 * \brief Check if subscribers exist 00128 * 00129 * \param event_type This is the type of event that the caller would like to 00130 * check for subscribers to. 00131 * 00132 * The rest of the arguments to this function specify additional parameters for 00133 * checking for subscriptions to subsets of an event type. The arguments must 00134 * in sets of: 00135 * \code 00136 * <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ] 00137 * \endcode 00138 * and must end with AST_EVENT_IE_END. 00139 * 00140 * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed 00141 * by a valid IE payload type. If the payload type specified is 00142 * AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided. 00143 * Otherwise, a payload must also be specified. 00144 * 00145 * \return This returns one of the values defined in the ast_event_subscriber_res 00146 * enum which will indicate if subscribers exist that match the given 00147 * criteria. 00148 * 00149 * Example usage: 00150 * 00151 * \code 00152 * if (ast_event_check_subscriber(AST_EVENT_MWI, 00153 * AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox, 00154 * AST_EVENT_IE_END) == AST_EVENT_SUB_NONE) { 00155 * return; 00156 * } 00157 * \endcode 00158 * 00159 * This example will check if there are any subscribers to MWI events for the 00160 * mailbox defined in the "mailbox" variable. 00161 */ 00162 enum ast_event_subscriber_res ast_event_check_subscriber(enum ast_event_type event_type, ...); 00163 00164 /*! 00165 * \brief Report current subscriptions to a subscription subscriber 00166 * 00167 * \arg sub the subscription subscriber 00168 * 00169 * \return nothing 00170 * 00171 * This reports all of the current subscribers to a subscriber of 00172 * subscribers to a specific event type. (Try saying that a few times fast). 00173 * 00174 * The idea here is that it is sometimes very useful for a module to know when 00175 * someone subscribes to events. However, when they first subscribe, this 00176 * provides that module the ability to request the event core report to them 00177 * all of the subscriptions to that event type that already exist. 00178 */ 00179 void ast_event_report_subs(const struct ast_event_sub *sub); 00180 00181 /*! 00182 * \brief Create a new event 00183 * 00184 * \param event_type The type of event to create 00185 * 00186 * The rest of the arguments to this function specify information elements to 00187 * add to the event. They are specified in the form: 00188 * \code 00189 * <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ] 00190 * \endcode 00191 * and must end with AST_EVENT_IE_END. 00192 * 00193 * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed 00194 * by a valid IE payload type. The payload type, EXISTS, should not be used here 00195 * because it makes no sense to do so. So, a payload must also be specified 00196 * after the IE payload type. 00197 * 00198 * \return This returns the event that has been created. If there is an error 00199 * creating the event, NULL will be returned. 00200 * 00201 * Example usage: 00202 * 00203 * \code 00204 * if (!(event = ast_event_new(AST_EVENT_MWI, 00205 * AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox, 00206 * AST_EVENT_IE_NEWMSGS, AST_EVENT_IE_PLTYPE_UINT, new, 00207 * AST_EVENT_IE_OLDMSGS, AST_EVENT_IE_PLTYPE_UINT, old, 00208 * AST_EVENT_IE_END))) { 00209 * return; 00210 * } 00211 * \endcode 00212 * 00213 * This creates a MWI event with 3 information elements, a mailbox which is 00214 * a string, and the number of new and old messages, specified as integers. 00215 */ 00216 struct ast_event *ast_event_new(enum ast_event_type event_type, ...); 00217 00218 /*! 00219 * \brief Destroy an event 00220 * 00221 * \param event the event to destroy 00222 * 00223 * \return Nothing 00224 * 00225 * \note Events that have been queued should *not* be destroyed by the code that 00226 * created the event. It will be automatically destroyed after being 00227 * dispatched to the appropriate subscribers. 00228 */ 00229 void ast_event_destroy(struct ast_event *event); 00230 00231 /*! 00232 * \brief Queue an event 00233 * 00234 * \param event the event to be queued 00235 * 00236 * \retval zero success 00237 * \retval non-zero failure 00238 * 00239 * This function queues an event to be dispatched to all of the appropriate 00240 * subscribers. This function will not block while the event is being 00241 * dispatched because a pool of event dispatching threads handle the event 00242 * queue. 00243 */ 00244 int ast_event_queue(struct ast_event *event); 00245 00246 /*! 00247 * \brief Queue and cache an event 00248 * 00249 * \param event the event to be queued and cached 00250 * 00251 * The rest of the arguments to this function specify information elements to 00252 * use for determining which events in the cache that this event should replace. 00253 * All events in the cache that match the specified criteria will be removed from 00254 * the cache and then this one will be added. The arguments are specified in 00255 * the form: 00256 * 00257 * \code 00258 * <enum ast_event_ie_type>, [enum ast_event_ie_pltype] 00259 * \endcode 00260 * and must end with AST_EVENT_IE_END. 00261 * 00262 * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed 00263 * by a valid IE payload type. If the payload type given is EXISTS, then all 00264 * events that contain that information element will be removed from the cache. 00265 * Otherwise, all events in the cache that contain an information element with 00266 * the same value as the new event will be removed. 00267 * 00268 * \note If more than one IE parameter is specified, they *all* must match for 00269 * the event to be removed from the cache. 00270 * 00271 * Example usage: 00272 * 00273 * \code 00274 * ast_event_queue_and_cache(event, 00275 * AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, 00276 * AST_EVENT_IE_END); 00277 * \endcode 00278 * 00279 * This example queues and caches an event. Any events in the cache that have 00280 * the same MAILBOX information element as this event will be removed. 00281 * 00282 * The purpose of caching events is so that the core can retain the last known 00283 * information for events that represent some sort of state. That way, when 00284 * code needs to find out the current state, it can query the cache. 00285 */ 00286 int ast_event_queue_and_cache(struct ast_event *event, ...); 00287 00288 /*! 00289 * \brief Retrieve an event from the cache 00290 * 00291 * \param ast_event_type The type of event to retrieve from the cache 00292 * 00293 * The rest of the arguments to this function specify information elements to 00294 * match for retrieving events from the cache. They are specified in the form: 00295 * \code 00296 * <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ] 00297 * \endcode 00298 * and must end with AST_EVENT_IE_END. 00299 * 00300 * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed 00301 * by a valid IE payload type. If the payload type specified is 00302 * AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided. 00303 * Otherwise, a payload must also be specified. 00304 * 00305 * \return A reference to an event retrieved from the cache. If no event was 00306 * found that matches the specified criteria, then NULL will be returned. 00307 * 00308 * \note If more than one event in the cache matches the specified criteria, only 00309 * one will be returned, and it is undefined which one it will be. 00310 * 00311 * \note The caller of this function *must* call ast_event_destroy() on the 00312 * returned event after it is done using it. 00313 * 00314 * Example Usage: 00315 * 00316 * \code 00317 * event = ast_event_get_cached(AST_EVENT_MWI, 00318 * AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox, 00319 * AST_EVENT_IE_END); 00320 * \endcode 00321 * 00322 * This example will check for an MWI event in the cache that matches the 00323 * specified mailbox. This would be the way to find out the last known state 00324 * of a mailbox without having to poll the mailbox directly. 00325 */ 00326 struct ast_event *ast_event_get_cached(enum ast_event_type, ...); 00327 00328 /*! 00329 * \brief Append an information element that has a string payload 00330 * 00331 * \param event the event that the IE will be appended to 00332 * \param ie_type the type of IE to append 00333 * \param str The string for the payload of the IE 00334 * 00335 * \retval 0 success 00336 * \retval -1 failure 00337 * 00338 * The pointer to the event will get updated with the new location for the event 00339 * that now contains the appended information element. If the re-allocation of 00340 * the memory for this event fails, it will be set to NULL. 00341 */ 00342 int ast_event_append_ie_str(struct ast_event **event, enum ast_event_ie_type ie_type, 00343 const char *str); 00344 00345 /*! 00346 * \brief Append an information element that has an integer payload 00347 * 00348 * \param event the event that the IE will be appended to 00349 * \param ie_type the type of IE to append 00350 * \param data The integer for the payload of the IE 00351 * 00352 * \retval 0 success 00353 * \retval -1 failure 00354 * 00355 * The pointer to the event will get updated with the new location for the event 00356 * that now contains the appended information element. If the re-allocation of 00357 * the memory for this event fails, it will be set to NULL. 00358 */ 00359 int ast_event_append_ie_uint(struct ast_event **event, enum ast_event_ie_type ie_type, 00360 uint32_t data); 00361 00362 /*! 00363 * \brief Append an information element that has a raw payload 00364 * 00365 * \param event the event that the IE will be appended to 00366 * \param ie_type the type of IE to append 00367 * \param data A pointer to the raw data for the payload of the IE 00368 * \param data_len The amount of data to copy into the payload 00369 * 00370 * \retval 0 success 00371 * \retval -1 failure 00372 * 00373 * The pointer to the event will get updated with the new location for the event 00374 * that now contains the appended information element. If the re-allocation of 00375 * the memory for this event fails, it will be set to NULL. 00376 */ 00377 int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_type, 00378 const void *data, size_t data_len); 00379 00380 /*! 00381 * \brief Get the value of an information element that has an integer payload 00382 * 00383 * \param event The event to get the IE from 00384 * \param ie_type the type of information element to retrieve 00385 * 00386 * \return This returns the payload of the information element with the given type. 00387 * However, an IE with a payload of 0, and the case where no IE is found 00388 * yield the same return value. 00389 */ 00390 uint32_t ast_event_get_ie_uint(const struct ast_event *event, enum ast_event_ie_type ie_type); 00391 00392 /*! 00393 * \brief Get the value of an information element that has a string payload 00394 * 00395 * \param event The event to get the IE from 00396 * \param ie_type the type of information element to retrieve 00397 * 00398 * \return This returns the payload of the information element with the given type. 00399 * If the information element isn't found, NULL will be returned. 00400 */ 00401 const char *ast_event_get_ie_str(const struct ast_event *event, enum ast_event_ie_type ie_type); 00402 00403 /*! 00404 * \brief Get the value of an information element that has a raw payload 00405 * 00406 * \param event The event to get the IE from 00407 * \param ie_type the type of information element to retrieve 00408 * 00409 * \return This returns the payload of the information element with the given type. 00410 * If the information element isn't found, NULL will be returned. 00411 */ 00412 const void *ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_ie_type ie_type); 00413 00414 /*! 00415 * \brief Get the type for an event 00416 * 00417 * \param event the event to get the type for 00418 * 00419 * \return the event type as represented by one of the values in the 00420 * ast_event_type enum 00421 */ 00422 enum ast_event_type ast_event_get_type(const struct ast_event *event); 00423 00424 /*! 00425 * \brief Initialize an event iterator instance 00426 * 00427 * \param iterator The iterator instance to initialize 00428 * \param event The event that will be iterated through 00429 * 00430 * \return Nothing 00431 */ 00432 void ast_event_iterator_init(struct ast_event_iterator *iterator, const struct ast_event *event); 00433 00434 /*! 00435 * \brief Move iterator instance to next IE 00436 * 00437 * \param iterator The iterator instance 00438 * 00439 * \retval 0 on success 00440 * \retval -1 if end is reached 00441 */ 00442 int ast_event_iterator_next(struct ast_event_iterator *iterator); 00443 00444 /*! 00445 * \brief Get the type of the current IE in the iterator instance 00446 * 00447 * \param iterator The iterator instance 00448 * 00449 * \return the ie type as represented by one of the value sin the 00450 * ast_event_ie_type enum 00451 */ 00452 enum ast_event_ie_type ast_event_iterator_get_ie_type(struct ast_event_iterator *iterator); 00453 00454 /*! 00455 * \brief Get the value of the current IE in the ierator as an integer payload 00456 * 00457 * \param iterator The iterator instance 00458 * 00459 * \return This returns the payload of the information element as a uint. 00460 */ 00461 uint32_t ast_event_iterator_get_ie_uint(struct ast_event_iterator *iterator); 00462 00463 /*! 00464 * \brief Get the value of the current IE in the iterator as a string payload 00465 * 00466 * \param iterator The iterator instance 00467 * 00468 * \return This returns the payload of the information element as a string. 00469 */ 00470 const char *ast_event_iterator_get_ie_str(struct ast_event_iterator *iterator); 00471 00472 /*! 00473 * \brief Get the value of the current IE in the iterator instance that has a raw payload 00474 * 00475 * \param iterator The iterator instance 00476 * 00477 * \return This returns the payload of the information element as type raw. 00478 */ 00479 void *ast_event_iterator_get_ie_raw(struct ast_event_iterator *iterator); 00480 00481 #if defined(__cplusplus) || defined(c_plusplus) 00482 } 00483 #endif 00484 00485 #endif /* AST_EVENT_H */