Mon Mar 19 11:30:27 2012

Asterisk developer's documentation


event.h

Go to the documentation of this file.
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 */

Generated on Mon Mar 19 11:30:27 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7