Fri Jun 19 12:09:43 2009

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

Generated on Fri Jun 19 12:09:43 2009 for Asterisk - the Open Source PBX by  doxygen 1.4.7