Mon Jun 27 16:50:53 2011

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, 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.  If failure is returned, the event must be destroyed
00401  *         by the caller of this function.
00402  */
00403 int ast_event_queue_and_cache(struct ast_event *event);
00404 
00405 /*!
00406  * \brief Retrieve an event from the cache
00407  *
00408  * \param ast_event_type The type of event to retrieve from the cache
00409  *
00410  * The rest of the arguments to this function specify information elements to
00411  * match for retrieving events from the cache.  They are specified in the form:
00412  * \code
00413  *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
00414  * \endcode
00415  * and must end with AST_EVENT_IE_END.
00416  *
00417  * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
00418  * by a valid IE payload type.  If the payload type specified is
00419  * AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided.
00420  * Otherwise, a payload must also be specified.
00421  *
00422  * \return A reference to an event retrieved from the cache.  If no event was
00423  *         found that matches the specified criteria, then NULL will be returned.
00424  *
00425  * \note If more than one event in the cache matches the specified criteria, only
00426  *       one will be returned, and it is undefined which one it will be.
00427  *
00428  * \note The caller of this function *must* call ast_event_destroy() on the
00429  *       returned event after it is done using it.
00430  *
00431  * Example Usage:
00432  *
00433  * \code
00434  * event = ast_event_get_cached(AST_EVENT_MWI,
00435  *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox,
00436  *     AST_EVENT_IE_END);
00437  * \endcode
00438  *
00439  * This example will check for an MWI event in the cache that matches the
00440  * specified mailbox.  This would be the way to find out the last known state
00441  * of a mailbox without having to poll the mailbox directly.
00442  */
00443 struct ast_event *ast_event_get_cached(enum ast_event_type, ...);
00444 
00445 /*!
00446  * \brief Append an information element that has a string payload
00447  *
00448  * \param event the event that the IE will be appended to
00449  * \param ie_type the type of IE to append
00450  * \param str The string for the payload of the IE
00451  *
00452  * \retval 0 success
00453  * \retval -1 failure
00454  *
00455  * The pointer to the event will get updated with the new location for the event
00456  * that now contains the appended information element.  If the re-allocation of
00457  * the memory for this event fails, it will be set to NULL.
00458  */
00459 int ast_event_append_ie_str(struct ast_event **event, enum ast_event_ie_type ie_type,
00460    const char *str);
00461 
00462 /*!
00463  * \brief Append an information element that has an integer payload
00464  *
00465  * \param event the event that the IE will be appended to
00466  * \param ie_type the type of IE to append
00467  * \param data The integer for the payload of the IE
00468  *
00469  * \retval 0 success
00470  * \retval -1 failure
00471  *
00472  * The pointer to the event will get updated with the new location for the event
00473  * that now contains the appended information element.  If the re-allocation of
00474  * the memory for this event fails, it will be set to NULL.
00475  */
00476 int ast_event_append_ie_uint(struct ast_event **event, enum ast_event_ie_type ie_type,
00477    uint32_t data);
00478 
00479 /*!
00480  * \brief Append an information element that has a bitflags payload
00481  *
00482  * \param event the event that the IE will be appended to
00483  * \param ie_type the type of IE to append
00484  * \param bitflags the flags that are the payload of the IE
00485  *
00486  * \retval 0 success
00487  * \retval -1 failure
00488  * \since 1.8
00489  *
00490  * The pointer to the event will get updated with the new location for the event
00491  * that now contains the appended information element.  If the re-allocation of
00492  * the memory for this event fails, it will be set to NULL.
00493  */
00494 int ast_event_append_ie_bitflags(struct ast_event **event, enum ast_event_ie_type ie_type,
00495    uint32_t bitflags);
00496 
00497 /*!
00498  * \brief Append an information element that has a raw payload
00499  *
00500  * \param event the event that the IE will be appended to
00501  * \param ie_type the type of IE to append
00502  * \param data A pointer to the raw data for the payload of the IE
00503  * \param data_len The amount of data to copy into the payload
00504  *
00505  * \retval 0 success
00506  * \retval -1 failure
00507  *
00508  * The pointer to the event will get updated with the new location for the event
00509  * that now contains the appended information element.  If the re-allocation of
00510  * the memory for this event fails, it will be set to NULL.
00511  */
00512 int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_type,
00513    const void *data, size_t data_len);
00514 
00515 /*!
00516  * \brief Append the global EID IE
00517  *
00518  * \param event the event to append IE to
00519  *
00520  * \note For ast_event_new() that includes IEs, this is done automatically
00521  *       for you.
00522  *
00523  * \retval 0 success
00524  * \retval -1 failure
00525  */
00526 int ast_event_append_eid(struct ast_event **event);
00527 
00528 /*!
00529  * \brief Get the value of an information element that has an integer payload
00530  *
00531  * \param event The event to get the IE from
00532  * \param ie_type the type of information element to retrieve
00533  *
00534  * \return This returns the payload of the information element with the given type.
00535  *         However, an IE with a payload of 0, and the case where no IE is found
00536  *         yield the same return value.
00537  */
00538 uint32_t ast_event_get_ie_uint(const struct ast_event *event, enum ast_event_ie_type ie_type);
00539 
00540 /*!
00541  * \brief Get the value of an information element that has a bitflags payload
00542  *
00543  * \param event The event to get the IE from
00544  * \param ie_type the type of information element to retrieve
00545  *
00546  * \return This returns the payload of the information element with the given type.
00547  *         However, an IE with a payload of 0, and the case where no IE is found
00548  *         yield the same return value.
00549  */
00550 uint32_t ast_event_get_ie_bitflags(const struct ast_event *event, enum ast_event_ie_type ie_type);
00551 
00552 /*!
00553  * \brief Get the value of an information element that has a string payload
00554  *
00555  * \param event The event to get the IE from
00556  * \param ie_type the type of information element to retrieve
00557  *
00558  * \return This returns the payload of the information element with the given type.
00559  *         If the information element isn't found, NULL will be returned.
00560  */
00561 const char *ast_event_get_ie_str(const struct ast_event *event, enum ast_event_ie_type ie_type);
00562 
00563 /*!
00564  * \brief Get the hash for the string payload of an IE
00565  *
00566  * \param event The event to get the IE from
00567  * \param ie_type the type of information element to retrieve the hash for
00568  *
00569  * \return This function returns the hash value as calculated by ast_str_hash()
00570  *         for the string payload.  This is stored in the event to avoid
00571  *         unnecessary string comparisons.
00572  */
00573 uint32_t ast_event_get_ie_str_hash(const struct ast_event *event, enum ast_event_ie_type ie_type);
00574 
00575 /*!
00576  * \brief Get the value of an information element that has a raw payload
00577  *
00578  * \param event The event to get the IE from
00579  * \param ie_type the type of information element to retrieve
00580  *
00581  * \return This returns the payload of the information element with the given type.
00582  *         If the information element isn't found, NULL will be returned.
00583  */
00584 const void *ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_ie_type ie_type);
00585 
00586 /*!
00587  * \brief Get the length of the raw payload for a particular IE
00588  *
00589  * \param event The event to get the IE payload length from
00590  * \param ie_type the type of information element to get the length of
00591  *
00592  * \return If an IE of type ie_type is found, its payload length is returned.
00593  *         Otherwise, 0 is returned.
00594  */
00595 uint16_t ast_event_get_ie_raw_payload_len(const struct ast_event *event, enum ast_event_ie_type ie_type);
00596 
00597 /*!
00598  * \brief Get the string representation of an information element type
00599  *
00600  * \param ie_type the information element type to get the string representation of
00601  *
00602  * \return the string representation of the information element type
00603  * \since 1.6.1
00604  */
00605 const char *ast_event_get_ie_type_name(enum ast_event_ie_type ie_type);
00606 
00607 /*!
00608  * \brief Get the payload type for a given information element type
00609  *
00610  * \param ie_type the information element type to get the payload type of
00611  *
00612  * \return the payload type for the provided IE type
00613  * \since 1.6.1
00614  */
00615 enum ast_event_ie_pltype ast_event_get_ie_pltype(enum ast_event_ie_type ie_type);
00616 
00617 /*!
00618  * \brief Get the type for an event
00619  *
00620  * \param event the event to get the type for
00621  *
00622  * \return the event type as represented by one of the values in the
00623  *         ast_event_type enum
00624  */
00625 enum ast_event_type ast_event_get_type(const struct ast_event *event);
00626 
00627 /*!
00628  * \brief Get the string representation of the type of the given event
00629  *
00630  * \arg event the event to get the type of
00631  *
00632  * \return the string representation of the event type of the provided event
00633  * \since 1.6.1
00634  */
00635 const char *ast_event_get_type_name(const struct ast_event *event);
00636 
00637 /*!
00638  * \brief Convert a string into an event type
00639  *
00640  * \param str the string to convert
00641  * \param event_type an output parameter for the event type
00642  *
00643  * \retval 0 success
00644  * \retval non-zero failure
00645  * \since 1.6.1
00646  */
00647 int ast_event_str_to_event_type(const char *str, enum ast_event_type *event_type);
00648 
00649 /*!
00650  * \brief Convert a string to an IE type
00651  *
00652  * \param str the string to convert
00653  * \param ie_type an output parameter for the IE type
00654  *
00655  * \retval 0 success
00656  * \retval non-zero failure
00657  * \since 1.6.1
00658  */
00659 int ast_event_str_to_ie_type(const char *str, enum ast_event_ie_type *ie_type);
00660 
00661 /*!
00662  * \brief Get the size of an event
00663  *
00664  * \param event the event to get the size of
00665  *
00666  * \return the number of bytes contained in the event
00667  * \since 1.6.1
00668  */
00669 size_t ast_event_get_size(const struct ast_event *event);
00670 
00671 /*!
00672  * \brief Initialize an event iterator instance
00673  *
00674  * \param iterator The iterator instance to initialize
00675  * \param event The event that will be iterated through
00676  *
00677  * \retval 0 Success, there are IEs available to iterate
00678  * \retval -1 Failure, there are no IEs in the event to iterate
00679  */
00680 int ast_event_iterator_init(struct ast_event_iterator *iterator, const struct ast_event *event);
00681 
00682 /*!
00683  * \brief Move iterator instance to next IE
00684  *
00685  * \param iterator The iterator instance
00686  *
00687  * \retval 0 on success
00688  * \retval -1 if end is reached
00689  */
00690 int ast_event_iterator_next(struct ast_event_iterator *iterator);
00691 
00692 /*!
00693  * \brief Get the type of the current IE in the iterator instance
00694  *
00695  * \param iterator The iterator instance
00696  *
00697  * \return the ie type as represented by one of the value sin the
00698  *         ast_event_ie_type enum
00699  */
00700 enum ast_event_ie_type ast_event_iterator_get_ie_type(struct ast_event_iterator *iterator);
00701 
00702 /*!
00703  * \brief Get the value of the current IE in the iterator as an integer payload
00704  *
00705  * \param iterator The iterator instance
00706  *
00707  * \return This returns the payload of the information element as a uint.
00708  */
00709 uint32_t ast_event_iterator_get_ie_uint(struct ast_event_iterator *iterator);
00710 
00711 /*!
00712  * \brief Get the value of the current IE in the iterator as a bitflags payload
00713  *
00714  * \param iterator The iterator instance
00715  *
00716  * \return This returns the payload of the information element as bitflags.
00717  */
00718 uint32_t ast_event_iterator_get_ie_bitflags(struct ast_event_iterator *iterator);
00719 
00720 /*!
00721  * \brief Get the value of the current IE in the iterator as a string payload
00722  *
00723  * \param iterator The iterator instance
00724  *
00725  * \return This returns the payload of the information element as a string.
00726  */
00727 const char *ast_event_iterator_get_ie_str(struct ast_event_iterator *iterator);
00728 
00729 /*!
00730  * \brief Get the value of the current IE in the iterator instance that has a raw payload
00731  *
00732  * \param iterator The iterator instance
00733  *
00734  * \return This returns the payload of the information element as type raw.
00735  */
00736 void *ast_event_iterator_get_ie_raw(struct ast_event_iterator *iterator);
00737 
00738 /*!
00739  * \brief Get the length of the raw payload for the current IE for an iterator
00740  *
00741  * \param iterator The IE iterator
00742  *
00743  * \return The payload length of the current IE
00744  */
00745 uint16_t ast_event_iterator_get_ie_raw_payload_len(struct ast_event_iterator *iterator);
00746 
00747 #if defined(__cplusplus) || defined(c_plusplus)
00748 }
00749 #endif
00750 
00751 #endif /* AST_EVENT_H */

Generated on Mon Jun 27 16:50:53 2011 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7