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 description Description of the subscription. 00082 * \param userdata data to be passed to the event callback 00083 * 00084 * The rest of the arguments to this function specify additional parameters for 00085 * the subscription to filter which events are passed to this subscriber. The 00086 * arguments must be in sets of: 00087 * \code 00088 * <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ] 00089 * \endcode 00090 * and must end with AST_EVENT_IE_END. 00091 * 00092 * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed 00093 * by a valid IE payload type. If the payload type specified is 00094 * AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided. 00095 * Otherwise, a payload must also be specified. 00096 * 00097 * \return This returns a reference to the subscription for use with 00098 * un-subscribing later. If there is a failure in creating the 00099 * subscription, NULL will be returned. 00100 * 00101 * Example usage: 00102 * 00103 * \code 00104 * peer->mwi_event_sub = ast_event_subscribe(AST_EVENT_MWI, mwi_event_cb, peer, 00105 * AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, peer->mailbox, 00106 * AST_EVENT_IE_END); 00107 * \endcode 00108 * 00109 * This creates a subscription to AST_EVENT_MWI events that contain an 00110 * information element, AST_EVENT_IE_MAILBOX, with the same string value 00111 * contained in peer->mailbox. Also, the event callback will be passed a 00112 * pointer to the peer. 00113 * 00114 * \note A NULL description will cause this function to crash, so watch out! 00115 */ 00116 struct ast_event_sub *ast_event_subscribe(enum ast_event_type event_type, 00117 ast_event_cb_t cb, const char *description, void *userdata, ...); 00118 00119 /*! 00120 * \brief Allocate a subscription, but do not activate it 00121 * 00122 * \param type the event type to subscribe to 00123 * \param cb the function to call when an event matches this subscription 00124 * \param userdata data to pass to the provided callback 00125 * 00126 * This function should be used when you want to dynamically build a 00127 * subscription. 00128 * 00129 * \return the allocated subscription, or NULL on failure 00130 * \since 1.6.1 00131 */ 00132 struct ast_event_sub *ast_event_subscribe_new(enum ast_event_type type, 00133 ast_event_cb_t cb, void *userdata); 00134 00135 /*! 00136 * \brief Destroy an allocated subscription 00137 * 00138 * \param sub the subscription to destroy 00139 * 00140 * This function should be used when a subscription is allocated with 00141 * ast_event_subscribe_new(), but for some reason, you want to destroy it 00142 * instead of activating it. This could be because of an error when 00143 * reading in the configuration for the dynamically built subscription. 00144 * \since 1.6.1 00145 */ 00146 void ast_event_sub_destroy(struct ast_event_sub *sub); 00147 00148 /*! 00149 * \brief Append a uint parameter to a subscription 00150 * 00151 * \param sub the dynamic subscription allocated with ast_event_subscribe_new() 00152 * \param ie_type the information element type for the parameter 00153 * \param uint the value that must be present in the event to match this subscription 00154 * 00155 * \retval 0 success 00156 * \retval non-zero failure 00157 * \since 1.6.1 00158 */ 00159 int ast_event_sub_append_ie_uint(struct ast_event_sub *sub, 00160 enum ast_event_ie_type ie_type, uint32_t uint); 00161 00162 /*! 00163 * \brief Append a bitflags parameter to a subscription 00164 * 00165 * \param sub the dynamic subscription allocated with ast_event_subscribe_new() 00166 * \param ie_type the information element type for the parameter 00167 * \param flags the flags that must be present in the event to match this subscription 00168 * 00169 * \retval 0 success 00170 * \retval non-zero failure 00171 * \since 1.8 00172 */ 00173 int ast_event_sub_append_ie_bitflags(struct ast_event_sub *sub, 00174 enum ast_event_ie_type ie_type, uint32_t flags); 00175 00176 /*! 00177 * \brief Append a string parameter to a subscription 00178 * 00179 * \param sub the dynamic subscription allocated with ast_event_subscribe_new() 00180 * \param ie_type the information element type for the parameter 00181 * \param str the string that must be present in the event to match this subscription 00182 * 00183 * \retval 0 success 00184 * \retval non-zero failure 00185 * \since 1.6.1 00186 */ 00187 int ast_event_sub_append_ie_str(struct ast_event_sub *sub, 00188 enum ast_event_ie_type ie_type, const char *str); 00189 00190 /*! 00191 * \brief Append a raw parameter to a subscription 00192 * 00193 * \param sub the dynamic subscription allocated with ast_event_subscribe_new() 00194 * \param ie_type the information element type for the parameter 00195 * \param data the data that must be present in the event to match this subscription 00196 * \param raw_datalen length of data 00197 * 00198 * \retval 0 success 00199 * \retval non-zero failure 00200 * \since 1.6.1 00201 */ 00202 int ast_event_sub_append_ie_raw(struct ast_event_sub *sub, 00203 enum ast_event_ie_type ie_type, void *data, size_t raw_datalen); 00204 00205 /*! 00206 * \brief Append an 'exists' parameter to a subscription 00207 * 00208 * \param sub the dynamic subscription allocated with ast_event_subscribe_new() 00209 * \param ie_type the information element type that must be present in the event 00210 * for it to match this subscription. 00211 * 00212 * \retval 0 success 00213 * \retval non-zero failure 00214 * \since 1.6.1 00215 */ 00216 int ast_event_sub_append_ie_exists(struct ast_event_sub *sub, 00217 enum ast_event_ie_type ie_type); 00218 00219 /*! 00220 * \brief Activate a dynamically built subscription 00221 * 00222 * \param sub the subscription to activate that was allocated using 00223 * ast_event_subscribe_new() 00224 * 00225 * Once a dynamically built subscription has had all of the parameters added 00226 * to it, it should be activated using this function. 00227 * 00228 * \retval 0 success 00229 * \retval non-zero failure 00230 * \since 1.6.1 00231 */ 00232 int ast_event_sub_activate(struct ast_event_sub *sub); 00233 00234 /*! 00235 * \brief Un-subscribe from events 00236 * 00237 * \param event_sub This is the reference to the subscription returned by 00238 * ast_event_subscribe. 00239 * 00240 * This function will remove a subscription and free the associated data 00241 * structures. 00242 * 00243 * \return NULL for convenience. 00244 * \version 1.6.1 return changed to NULL 00245 */ 00246 struct ast_event_sub *ast_event_unsubscribe(struct ast_event_sub *event_sub); 00247 00248 /*! 00249 * \brief Get description for a subscription 00250 * 00251 * \param sub subscription 00252 * 00253 * \return string description of the subscription 00254 */ 00255 const char *ast_event_subscriber_get_description(struct ast_event_sub *sub); 00256 00257 /*! 00258 * \brief Check if subscribers exist 00259 * 00260 * \param event_type This is the type of event that the caller would like to 00261 * check for subscribers to. 00262 * 00263 * The rest of the arguments to this function specify additional parameters for 00264 * checking for subscriptions to subsets of an event type. The arguments must 00265 * in sets of: 00266 * \code 00267 * <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ] 00268 * \endcode 00269 * and must end with AST_EVENT_IE_END. 00270 * 00271 * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed 00272 * by a valid IE payload type. If the payload type specified is 00273 * AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided. 00274 * Otherwise, a payload must also be specified. 00275 * 00276 * \return This returns one of the values defined in the ast_event_subscriber_res 00277 * enum which will indicate if subscribers exist that match the given 00278 * criteria. 00279 * 00280 * Example usage: 00281 * 00282 * \code 00283 * if (ast_event_check_subscriber(AST_EVENT_MWI, 00284 * AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox, 00285 * AST_EVENT_IE_END) == AST_EVENT_SUB_NONE) { 00286 * return; 00287 * } 00288 * \endcode 00289 * 00290 * This example will check if there are any subscribers to MWI events for the 00291 * mailbox defined in the "mailbox" variable. 00292 */ 00293 enum ast_event_subscriber_res ast_event_check_subscriber(enum ast_event_type event_type, ...); 00294 00295 /*! 00296 * \brief Report current subscriptions to a subscription subscriber 00297 * 00298 * \arg sub the subscription subscriber 00299 * 00300 * \return nothing 00301 * 00302 * This reports all of the current subscribers to a subscriber of 00303 * subscribers to a specific event type. (Try saying that a few times fast). 00304 * 00305 * The idea here is that it is sometimes very useful for a module to know when 00306 * someone subscribes to events. However, when they first subscribe, this 00307 * provides that module the ability to request the event core report to them 00308 * all of the subscriptions to that event type that already exist. 00309 */ 00310 void ast_event_report_subs(const struct ast_event_sub *sub); 00311 00312 /*! 00313 * \brief Dump the event cache for the subscriber 00314 * \since 1.6.1 00315 */ 00316 void ast_event_dump_cache(const struct ast_event_sub *event_sub); 00317 00318 /*! 00319 * \brief Create a new event 00320 * 00321 * \param event_type The type of event to create 00322 * 00323 * The rest of the arguments to this function specify information elements to 00324 * add to the event. They are specified in the form: 00325 * \code 00326 * <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ] 00327 * \endcode 00328 * and must end with AST_EVENT_IE_END. 00329 * 00330 * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed 00331 * by a valid IE payload type. The payload type, EXISTS, should not be used here 00332 * because it makes no sense to do so. So, a payload must also be specified 00333 * after the IE payload type. 00334 * 00335 * \note The EID IE will be appended automatically when this function is used 00336 * with at least one IE specified. 00337 * 00338 * \return This returns the event that has been created. If there is an error 00339 * creating the event, NULL will be returned. 00340 * 00341 * Example usage: 00342 * 00343 * \code 00344 * if (!(event = ast_event_new(AST_EVENT_MWI, 00345 * AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox, 00346 * AST_EVENT_IE_NEWMSGS, AST_EVENT_IE_PLTYPE_UINT, new, 00347 * AST_EVENT_IE_OLDMSGS, AST_EVENT_IE_PLTYPE_UINT, old, 00348 * AST_EVENT_IE_END))) { 00349 * return; 00350 * } 00351 * \endcode 00352 * 00353 * This creates a MWI event with 3 information elements, a mailbox which is 00354 * a string, and the number of new and old messages, specified as integers. 00355 */ 00356 struct ast_event *ast_event_new(enum ast_event_type event_type, ...); 00357 00358 /*! 00359 * \brief Destroy an event 00360 * 00361 * \param event the event to destroy 00362 * 00363 * \return Nothing 00364 * 00365 * \note Events that have been queued should *not* be destroyed by the code that 00366 * created the event. It will be automatically destroyed after being 00367 * dispatched to the appropriate subscribers. 00368 */ 00369 void ast_event_destroy(struct ast_event *event); 00370 00371 /*! 00372 * \brief Queue an event 00373 * 00374 * \param event the event to be queued 00375 * 00376 * \retval zero success 00377 * \retval non-zero failure. Note that the caller of this function is 00378 * responsible for destroying the event in the case of a failure. 00379 * 00380 * This function queues an event to be dispatched to all of the appropriate 00381 * subscribers. This function will not block while the event is being 00382 * dispatched because the event is queued up for a dispatching thread 00383 * to handle. 00384 */ 00385 int ast_event_queue(struct ast_event *event); 00386 00387 /*! 00388 * \brief Queue and cache an event 00389 * 00390 * \param event the event to be queued and cached 00391 * 00392 * \details 00393 * The purpose of caching events is so that the core can retain the last known 00394 * information for events that represent some sort of state. That way, when 00395 * code needs to find out the current state, it can query the cache. 00396 * 00397 * The event API already knows which events can be cached and how to cache them. 00398 * 00399 * \retval 0 success 00400 * \retval non-zero failure. 00401 */ 00402 int ast_event_queue_and_cache(struct ast_event *event); 00403 00404 /*! 00405 * \brief Retrieve an event from the cache 00406 * 00407 * \param ast_event_type The type of event to retrieve from the cache 00408 * 00409 * The rest of the arguments to this function specify information elements to 00410 * match for retrieving events from the cache. They are specified in the form: 00411 * \code 00412 * <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ] 00413 * \endcode 00414 * and must end with AST_EVENT_IE_END. 00415 * 00416 * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed 00417 * by a valid IE payload type. If the payload type specified is 00418 * AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided. 00419 * Otherwise, a payload must also be specified. 00420 * 00421 * \return A reference to an event retrieved from the cache. If no event was 00422 * found that matches the specified criteria, then NULL will be returned. 00423 * 00424 * \note If more than one event in the cache matches the specified criteria, only 00425 * one will be returned, and it is undefined which one it will be. 00426 * 00427 * \note The caller of this function *must* call ast_event_destroy() on the 00428 * returned event after it is done using it. 00429 * 00430 * Example Usage: 00431 * 00432 * \code 00433 * event = ast_event_get_cached(AST_EVENT_MWI, 00434 * AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox, 00435 * AST_EVENT_IE_END); 00436 * \endcode 00437 * 00438 * This example will check for an MWI event in the cache that matches the 00439 * specified mailbox. This would be the way to find out the last known state 00440 * of a mailbox without having to poll the mailbox directly. 00441 */ 00442 struct ast_event *ast_event_get_cached(enum ast_event_type, ...); 00443 00444 /*! 00445 * \brief Append an information element that has a string payload 00446 * 00447 * \param event the event that the IE will be appended to 00448 * \param ie_type the type of IE to append 00449 * \param str The string for the payload of the IE 00450 * 00451 * \retval 0 success 00452 * \retval -1 failure 00453 * 00454 * The pointer to the event will get updated with the new location for the event 00455 * that now contains the appended information element. If the re-allocation of 00456 * the memory for this event fails, it will be set to NULL. 00457 */ 00458 int ast_event_append_ie_str(struct ast_event **event, enum ast_event_ie_type ie_type, 00459 const char *str); 00460 00461 /*! 00462 * \brief Append an information element that has an integer payload 00463 * 00464 * \param event the event that the IE will be appended to 00465 * \param ie_type the type of IE to append 00466 * \param data The integer for the payload of the IE 00467 * 00468 * \retval 0 success 00469 * \retval -1 failure 00470 * 00471 * The pointer to the event will get updated with the new location for the event 00472 * that now contains the appended information element. If the re-allocation of 00473 * the memory for this event fails, it will be set to NULL. 00474 */ 00475 int ast_event_append_ie_uint(struct ast_event **event, enum ast_event_ie_type ie_type, 00476 uint32_t data); 00477 00478 /*! 00479 * \brief Append an information element that has a bitflags payload 00480 * 00481 * \param event the event that the IE will be appended to 00482 * \param ie_type the type of IE to append 00483 * \param bitflags the flags that are the payload of the IE 00484 * 00485 * \retval 0 success 00486 * \retval -1 failure 00487 * \since 1.8 00488 * 00489 * The pointer to the event will get updated with the new location for the event 00490 * that now contains the appended information element. If the re-allocation of 00491 * the memory for this event fails, it will be set to NULL. 00492 */ 00493 int ast_event_append_ie_bitflags(struct ast_event **event, enum ast_event_ie_type ie_type, 00494 uint32_t bitflags); 00495 00496 /*! 00497 * \brief Append an information element that has a raw payload 00498 * 00499 * \param event the event that the IE will be appended to 00500 * \param ie_type the type of IE to append 00501 * \param data A pointer to the raw data for the payload of the IE 00502 * \param data_len The amount of data to copy into the payload 00503 * 00504 * \retval 0 success 00505 * \retval -1 failure 00506 * 00507 * The pointer to the event will get updated with the new location for the event 00508 * that now contains the appended information element. If the re-allocation of 00509 * the memory for this event fails, it will be set to NULL. 00510 */ 00511 int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_type, 00512 const void *data, size_t data_len); 00513 00514 /*! 00515 * \brief Append the global EID IE 00516 * 00517 * \param event the event to append IE to 00518 * 00519 * \note For ast_event_new() that includes IEs, this is done automatically 00520 * for you. 00521 * 00522 * \retval 0 success 00523 * \retval -1 failure 00524 */ 00525 int ast_event_append_eid(struct ast_event **event); 00526 00527 /*! 00528 * \brief Get the value of an information element that has an integer payload 00529 * 00530 * \param event The event to get the IE from 00531 * \param ie_type the type of information element to retrieve 00532 * 00533 * \return This returns the payload of the information element with the given type. 00534 * However, an IE with a payload of 0, and the case where no IE is found 00535 * yield the same return value. 00536 */ 00537 uint32_t ast_event_get_ie_uint(const struct ast_event *event, enum ast_event_ie_type ie_type); 00538 00539 /*! 00540 * \brief Get the value of an information element that has a bitflags payload 00541 * 00542 * \param event The event to get the IE from 00543 * \param ie_type the type of information element to retrieve 00544 * 00545 * \return This returns the payload of the information element with the given type. 00546 * However, an IE with a payload of 0, and the case where no IE is found 00547 * yield the same return value. 00548 */ 00549 uint32_t ast_event_get_ie_bitflags(const struct ast_event *event, enum ast_event_ie_type ie_type); 00550 00551 /*! 00552 * \brief Get the value of an information element that has a string payload 00553 * 00554 * \param event The event to get the IE from 00555 * \param ie_type the type of information element to retrieve 00556 * 00557 * \return This returns the payload of the information element with the given type. 00558 * If the information element isn't found, NULL will be returned. 00559 */ 00560 const char *ast_event_get_ie_str(const struct ast_event *event, enum ast_event_ie_type ie_type); 00561 00562 /*! 00563 * \brief Get the hash for the string payload of an IE 00564 * 00565 * \param event The event to get the IE from 00566 * \param ie_type the type of information element to retrieve the hash for 00567 * 00568 * \return This function returns the hash value as calculated by ast_str_hash() 00569 * for the string payload. This is stored in the event to avoid 00570 * unnecessary string comparisons. 00571 */ 00572 uint32_t ast_event_get_ie_str_hash(const struct ast_event *event, enum ast_event_ie_type ie_type); 00573 00574 /*! 00575 * \brief Get the value of an information element that has a raw payload 00576 * 00577 * \param event The event to get the IE from 00578 * \param ie_type the type of information element to retrieve 00579 * 00580 * \return This returns the payload of the information element with the given type. 00581 * If the information element isn't found, NULL will be returned. 00582 */ 00583 const void *ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_ie_type ie_type); 00584 00585 /*! 00586 * \brief Get the length of the raw payload for a particular IE 00587 * 00588 * \param event The event to get the IE payload length from 00589 * \param ie_type the type of information element to get the length of 00590 * 00591 * \return If an IE of type ie_type is found, its payload length is returned. 00592 * Otherwise, 0 is returned. 00593 */ 00594 uint16_t ast_event_get_ie_raw_payload_len(const struct ast_event *event, enum ast_event_ie_type ie_type); 00595 00596 /*! 00597 * \brief Get the string representation of an information element type 00598 * 00599 * \param ie_type the information element type to get the string representation of 00600 * 00601 * \return the string representation of the information element type 00602 * \since 1.6.1 00603 */ 00604 const char *ast_event_get_ie_type_name(enum ast_event_ie_type ie_type); 00605 00606 /*! 00607 * \brief Get the payload type for a given information element type 00608 * 00609 * \param ie_type the information element type to get the payload type of 00610 * 00611 * \return the payload type for the provided IE type 00612 * \since 1.6.1 00613 */ 00614 enum ast_event_ie_pltype ast_event_get_ie_pltype(enum ast_event_ie_type ie_type); 00615 00616 /*! 00617 * \brief Get the type for an event 00618 * 00619 * \param event the event to get the type for 00620 * 00621 * \return the event type as represented by one of the values in the 00622 * ast_event_type enum 00623 */ 00624 enum ast_event_type ast_event_get_type(const struct ast_event *event); 00625 00626 /*! 00627 * \brief Get the string representation of the type of the given event 00628 * 00629 * \arg event the event to get the type of 00630 * 00631 * \return the string representation of the event type of the provided event 00632 * \since 1.6.1 00633 */ 00634 const char *ast_event_get_type_name(const struct ast_event *event); 00635 00636 /*! 00637 * \brief Convert a string into an event type 00638 * 00639 * \param str the string to convert 00640 * \param event_type an output parameter for the event type 00641 * 00642 * \retval 0 success 00643 * \retval non-zero failure 00644 * \since 1.6.1 00645 */ 00646 int ast_event_str_to_event_type(const char *str, enum ast_event_type *event_type); 00647 00648 /*! 00649 * \brief Convert a string to an IE type 00650 * 00651 * \param str the string to convert 00652 * \param ie_type an output parameter for the IE type 00653 * 00654 * \retval 0 success 00655 * \retval non-zero failure 00656 * \since 1.6.1 00657 */ 00658 int ast_event_str_to_ie_type(const char *str, enum ast_event_ie_type *ie_type); 00659 00660 /*! 00661 * \brief Get the size of an event 00662 * 00663 * \param event the event to get the size of 00664 * 00665 * \return the number of bytes contained in the event 00666 * \since 1.6.1 00667 */ 00668 size_t ast_event_get_size(const struct ast_event *event); 00669 00670 /*! 00671 * \brief Initialize an event iterator instance 00672 * 00673 * \param iterator The iterator instance to initialize 00674 * \param event The event that will be iterated through 00675 * 00676 * \retval 0 Success, there are IEs available to iterate 00677 * \retval -1 Failure, there are no IEs in the event to iterate 00678 */ 00679 int ast_event_iterator_init(struct ast_event_iterator *iterator, const struct ast_event *event); 00680 00681 /*! 00682 * \brief Move iterator instance to next IE 00683 * 00684 * \param iterator The iterator instance 00685 * 00686 * \retval 0 on success 00687 * \retval -1 if end is reached 00688 */ 00689 int ast_event_iterator_next(struct ast_event_iterator *iterator); 00690 00691 /*! 00692 * \brief Get the type of the current IE in the iterator instance 00693 * 00694 * \param iterator The iterator instance 00695 * 00696 * \return the ie type as represented by one of the value sin the 00697 * ast_event_ie_type enum 00698 */ 00699 enum ast_event_ie_type ast_event_iterator_get_ie_type(struct ast_event_iterator *iterator); 00700 00701 /*! 00702 * \brief Get the value of the current IE in the iterator as an integer payload 00703 * 00704 * \param iterator The iterator instance 00705 * 00706 * \return This returns the payload of the information element as a uint. 00707 */ 00708 uint32_t ast_event_iterator_get_ie_uint(struct ast_event_iterator *iterator); 00709 00710 /*! 00711 * \brief Get the value of the current IE in the iterator as a bitflags payload 00712 * 00713 * \param iterator The iterator instance 00714 * 00715 * \return This returns the payload of the information element as bitflags. 00716 */ 00717 uint32_t ast_event_iterator_get_ie_bitflags(struct ast_event_iterator *iterator); 00718 00719 /*! 00720 * \brief Get the value of the current IE in the iterator as a string payload 00721 * 00722 * \param iterator The iterator instance 00723 * 00724 * \return This returns the payload of the information element as a string. 00725 */ 00726 const char *ast_event_iterator_get_ie_str(struct ast_event_iterator *iterator); 00727 00728 /*! 00729 * \brief Get the value of the current IE in the iterator instance that has a raw payload 00730 * 00731 * \param iterator The iterator instance 00732 * 00733 * \return This returns the payload of the information element as type raw. 00734 */ 00735 void *ast_event_iterator_get_ie_raw(struct ast_event_iterator *iterator); 00736 00737 /*! 00738 * \brief Get the length of the raw payload for the current IE for an iterator 00739 * 00740 * \param iterator The IE iterator 00741 * 00742 * \return The payload length of the current IE 00743 */ 00744 uint16_t ast_event_iterator_get_ie_raw_payload_len(struct ast_event_iterator *iterator); 00745 00746 /*! 00747 * \brief Get the minimum length of an ast_event. 00748 * 00749 * \return minimum amount of memory that will be consumed by any ast_event. 00750 */ 00751 size_t ast_event_minimum_length(void); 00752 00753 #if defined(__cplusplus) || defined(c_plusplus) 00754 } 00755 #endif 00756 00757 #endif /* AST_EVENT_H */