Thu Jul 9 13:40:33 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, Digium, Inc.
00005  *
00006  * Russell Bryant <russell@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*!
00020  * \file
00021  * \author Russell Bryant <russell@digium.com>
00022  * \ref AstGenericEvents
00023  */
00024 
00025 /*!
00026  * \page AstGenericEvents Generic event system
00027  *
00028  * The purpose of this API is to provide a generic way to share events between
00029  * Asterisk modules.  Code can generate events, and other code can subscribe to
00030  * them.
00031  *
00032  * Events have an associated event type, as well as information elements.  The
00033  * information elements are the meta data that go along with each event.  For
00034  * example, in the case of message waiting indication, the event type is MWI,
00035  * and each MWI event contains at least three information elements: the
00036  * mailbox, the number of new messages, and the number of old messages.
00037  *
00038  * Subscriptions to events consist of an event type and information elements,
00039  * as well.  Subscriptions can be to all events, or a certain subset of events.
00040  * If an event type is provided, only events of that type will be sent to this
00041  * subscriber.  Furthermore, if information elements are supplied with the
00042  * subscription, only events that contain the specified information elements
00043  * with specified values will be sent to the subscriber.  For example, when a
00044  * SIP phone subscribes to MWI for mailbox 1234, then chan_sip can subscribe
00045  * to internal Asterisk MWI events with the MAILBOX information element with
00046  * a value of "1234".
00047  *
00048  * Another key feature of this event system is the ability to cache events.
00049  * It is useful for some types of events to be able to remember the last known
00050  * value.  These are usually events that indicate some kind of state change.
00051  * In the example of MWI, app_voicemail can instruct the event core to cache
00052  * these events based on the mailbox.  So, the last known MWI state of each
00053  * mailbox will be cached, and other modules can retrieve this information
00054  * on demand without having to poll the mailbox directly.
00055  */
00056 
00057 #ifndef AST_EVENT_H
00058 #define AST_EVENT_H
00059 
00060 #if defined(__cplusplus) || defined(c_plusplus)
00061 extern "C" {
00062 #endif
00063 
00064 #include "asterisk/event_defs.h"
00065 
00066 /*! 
00067  * \brief Subscriber event callback type
00068  *
00069  * \param event the event being passed to the subscriber
00070  * \param userdata the data provider in the call to ast_event_subscribe()
00071  *
00072  * \return The event callbacks do not return anything.
00073  */
00074 typedef void (*ast_event_cb_t)(const struct ast_event *event, void *userdata);
00075 
00076 /*! 
00077  * \brief Subscribe to events
00078  *
00079  * \param event_type The type of events to subscribe to
00080  * \param cb The function to be called with events
00081  * \param userdata data to be passed to the event callback
00082  *
00083  * The rest of the arguments to this function specify additional parameters for
00084  * the subscription to filter which events are passed to this subscriber.  The
00085  * arguments must be in sets of:
00086  * \code
00087  *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
00088  * \endcode
00089  * and must end with AST_EVENT_IE_END.
00090  *
00091  * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
00092  * by a valid IE payload type.  If the payload type specified is
00093  * AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided.
00094  * Otherwise, a payload must also be specified.
00095  *
00096  * \return This returns a reference to the subscription for use with
00097  *         un-subscribing later.  If there is a failure in creating the
00098  *         subscription, NULL will be returned.
00099  *
00100  * Example usage:
00101  *
00102  * \code
00103  * peer->mwi_event_sub = ast_event_subscribe(AST_EVENT_MWI, mwi_event_cb, peer,
00104  *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, peer->mailbox,
00105  *     AST_EVENT_IE_END);
00106  * \endcode
00107  *
00108  * This creates a subscription to AST_EVENT_MWI events that contain an
00109  * information element, AST_EVENT_IE_MAILBOX, with the same string value
00110  * contained in peer->mailbox.  Also, the event callback will be passed a
00111  * pointer to the peer.
00112  */
00113 struct ast_event_sub *ast_event_subscribe(enum ast_event_type event_type, 
00114    ast_event_cb_t cb, void *userdata, ...);
00115 
00116 /*!
00117  * \brief Un-subscribe from events
00118  *
00119  * \param event_sub This is the reference to the subscription returned by
00120  *        ast_event_subscribe.
00121  * 
00122  * \return Nothing
00123  */
00124 void ast_event_unsubscribe(struct ast_event_sub *event_sub);
00125 
00126 /*!
00127  * \brief Check if subscribers exist
00128  *
00129  * \param event_type This is the type of event that the caller would like to
00130  *        check for subscribers to.
00131  *
00132  * The rest of the arguments to this function specify additional parameters for
00133  * checking for subscriptions to subsets of an event type. The arguments must
00134  * in sets of:
00135  * \code
00136  *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
00137  * \endcode
00138  * and must end with AST_EVENT_IE_END.
00139  *
00140  * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
00141  * by a valid IE payload type.  If the payload type specified is
00142  * AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided.
00143  * Otherwise, a payload must also be specified.
00144  *
00145  * \return This returns one of the values defined in the ast_event_subscriber_res
00146  *         enum which will indicate if subscribers exist that match the given
00147  *         criteria.
00148  *
00149  * Example usage:
00150  *
00151  * \code
00152  * if (ast_event_check_subscriber(AST_EVENT_MWI,
00153  *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox,
00154  *     AST_EVENT_IE_END) == AST_EVENT_SUB_NONE) {
00155  *       return;
00156  * }
00157  * \endcode
00158  *
00159  * This example will check if there are any subscribers to MWI events for the 
00160  * mailbox defined in the "mailbox" variable.
00161  */
00162 enum ast_event_subscriber_res ast_event_check_subscriber(enum ast_event_type event_type, ...);
00163 
00164 /*!
00165  * \brief Report current subscriptions to a subscription subscriber
00166  *
00167  * \arg sub the subscription subscriber
00168  *
00169  * \return nothing
00170  *
00171  * This reports all of the current subscribers to a subscriber of
00172  * subscribers to a specific event type.  (Try saying that a few times fast).
00173  *
00174  * The idea here is that it is sometimes very useful for a module to know when
00175  * someone subscribes to events.  However, when they first subscribe, this
00176  * provides that module the ability to request the event core report to them
00177  * all of the subscriptions to that event type that already exist.
00178  */
00179 void ast_event_report_subs(const struct ast_event_sub *sub);
00180 
00181 /*!
00182  * \brief Create a new event
00183  *
00184  * \param event_type The type of event to create
00185  *
00186  * The rest of the arguments to this function specify information elements to
00187  * add to the event.  They are specified in the form:
00188  * \code
00189  *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
00190  * \endcode
00191  * and must end with AST_EVENT_IE_END.
00192  *
00193  * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
00194  * by a valid IE payload type.  The payload type, EXISTS, should not be used here
00195  * because it makes no sense to do so.  So, a payload must also be specified
00196  * after the IE payload type.
00197  *
00198  * \return This returns the event that has been created.  If there is an error
00199  *         creating the event, NULL will be returned.
00200  *
00201  * Example usage:
00202  *
00203  * \code
00204  * if (!(event = ast_event_new(AST_EVENT_MWI,
00205  *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox,
00206  *     AST_EVENT_IE_NEWMSGS, AST_EVENT_IE_PLTYPE_UINT, new,
00207  *     AST_EVENT_IE_OLDMSGS, AST_EVENT_IE_PLTYPE_UINT, old,
00208  *     AST_EVENT_IE_END))) {
00209  *       return;
00210  * }
00211  * \endcode
00212  *
00213  * This creates a MWI event with 3 information elements, a mailbox which is
00214  * a string, and the number of new and old messages, specified as integers.
00215  */
00216 struct ast_event *ast_event_new(enum ast_event_type event_type, ...);
00217 
00218 /*!
00219  * \brief Destroy an event
00220  *
00221  * \param event the event to destroy
00222  *
00223  * \return Nothing
00224  *
00225  * \note Events that have been queued should *not* be destroyed by the code that
00226  *       created the event.  It will be automatically destroyed after being
00227  *       dispatched to the appropriate subscribers.
00228  */
00229 void ast_event_destroy(struct ast_event *event);
00230 
00231 /*!
00232  * \brief Queue an event
00233  *
00234  * \param event the event to be queued
00235  *
00236  * \retval zero success
00237  * \retval non-zero failure
00238  *
00239  * This function queues an event to be dispatched to all of the appropriate
00240  * subscribers.  This function will not block while the event is being
00241  * dispatched because a pool of event dispatching threads handle the event 
00242  * queue.
00243  */
00244 int ast_event_queue(struct ast_event *event);
00245 
00246 /*!
00247  * \brief Queue and cache an event
00248  *
00249  * \param event the event to be queued and cached
00250  *
00251  * The rest of the arguments to this function specify information elements to
00252  * use for determining which events in the cache that this event should replace.
00253  * All events in the cache that match the specified criteria will be removed from
00254  * the cache and then this one will be added.  The arguments are specified in 
00255  * the form:
00256  *
00257  * \code
00258  *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype]
00259  * \endcode
00260  * and must end with AST_EVENT_IE_END.
00261  *
00262  * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
00263  * by a valid IE payload type.  If the payload type given is EXISTS, then all
00264  * events that contain that information element will be removed from the cache.
00265  * Otherwise, all events in the cache that contain an information element with
00266  * the same value as the new event will be removed.
00267  *
00268  * \note If more than one IE parameter is specified, they *all* must match for
00269  *       the event to be removed from the cache.
00270  *
00271  * Example usage:
00272  *
00273  * \code
00274  * ast_event_queue_and_cache(event,
00275  *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR,
00276  *     AST_EVENT_IE_END);
00277  * \endcode
00278  *
00279  * This example queues and caches an event.  Any events in the cache that have
00280  * the same MAILBOX information element as this event will be removed.
00281  *
00282  * The purpose of caching events is so that the core can retain the last known
00283  * information for events that represent some sort of state.  That way, when
00284  * code needs to find out the current state, it can query the cache.
00285  */
00286 int ast_event_queue_and_cache(struct ast_event *event, ...);
00287 
00288 /*!
00289  * \brief Retrieve an event from the cache
00290  *
00291  * \param ast_event_type The type of event to retrieve from the cache
00292  *
00293  * The rest of the arguments to this function specify information elements to
00294  * match for retrieving events from the cache.  They are specified in the form:
00295  * \code
00296  *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
00297  * \endcode
00298  * and must end with AST_EVENT_IE_END.
00299  *
00300  * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
00301  * by a valid IE payload type.  If the payload type specified is
00302  * AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided.
00303  * Otherwise, a payload must also be specified.
00304  *
00305  * \return A reference to an event retrieved from the cache.  If no event was
00306  *         found that matches the specified criteria, then NULL will be returned.
00307  *
00308  * \note If more than one event in the cache matches the specified criteria, only
00309  *       one will be returned, and it is undefined which one it will be.
00310  *
00311  * \note The caller of this function *must* call ast_event_destroy() on the
00312  *       returned event after it is done using it.
00313  *
00314  * Example Usage:
00315  *
00316  * \code
00317  * event = ast_event_get_cached(AST_EVENT_MWI,
00318  *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox,
00319  *     AST_EVENT_IE_END);
00320  * \endcode
00321  *
00322  * This example will check for an MWI event in the cache that matches the
00323  * specified mailbox.  This would be the way to find out the last known state
00324  * of a mailbox without having to poll the mailbox directly.
00325  */
00326 struct ast_event *ast_event_get_cached(enum ast_event_type, ...);
00327 
00328 /*!
00329  * \brief Append an information element that has a string payload
00330  *
00331  * \param event the event that the IE will be appended to
00332  * \param ie_type the type of IE to append
00333  * \param str The string for the payload of the IE
00334  *
00335  * \retval 0 success
00336  * \retval -1 failure
00337  *
00338  * The pointer to the event will get updated with the new location for the event
00339  * that now contains the appended information element.  If the re-allocation of
00340  * the memory for this event fails, it will be set to NULL.
00341  */
00342 int ast_event_append_ie_str(struct ast_event **event, enum ast_event_ie_type ie_type,
00343    const char *str);
00344 
00345 /*!
00346  * \brief Append an information element that has an integer payload
00347  *
00348  * \param event the event that the IE will be appended to
00349  * \param ie_type the type of IE to append
00350  * \param data The integer for the payload of the IE
00351  *
00352  * \retval 0 success
00353  * \retval -1 failure
00354  *
00355  * The pointer to the event will get updated with the new location for the event
00356  * that now contains the appended information element.  If the re-allocation of
00357  * the memory for this event fails, it will be set to NULL.
00358  */
00359 int ast_event_append_ie_uint(struct ast_event **event, enum ast_event_ie_type ie_type,
00360    uint32_t data);
00361 
00362 /*!
00363  * \brief Append an information element that has a raw payload
00364  *
00365  * \param event the event that the IE will be appended to
00366  * \param ie_type the type of IE to append
00367  * \param data A pointer to the raw data for the payload of the IE
00368  * \param data_len The amount of data to copy into the payload
00369  *
00370  * \retval 0 success
00371  * \retval -1 failure
00372  *
00373  * The pointer to the event will get updated with the new location for the event
00374  * that now contains the appended information element.  If the re-allocation of
00375  * the memory for this event fails, it will be set to NULL.
00376  */
00377 int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_type,
00378    const void *data, size_t data_len);
00379 
00380 /*!
00381  * \brief Get the value of an information element that has an integer payload
00382  *
00383  * \param event The event to get the IE from
00384  * \param ie_type the type of information element to retrieve
00385  * 
00386  * \return This returns the payload of the information element with the given type.
00387  *         However, an IE with a payload of 0, and the case where no IE is found
00388  *         yield the same return value.
00389  */
00390 uint32_t ast_event_get_ie_uint(const struct ast_event *event, enum ast_event_ie_type ie_type);
00391 
00392 /*!
00393  * \brief Get the value of an information element that has a string payload
00394  *
00395  * \param event The event to get the IE from
00396  * \param ie_type the type of information element to retrieve
00397  * 
00398  * \return This returns the payload of the information element with the given type.
00399  *         If the information element isn't found, NULL will be returned.
00400  */
00401 const char *ast_event_get_ie_str(const struct ast_event *event, enum ast_event_ie_type ie_type);
00402 
00403 /*!
00404  * \brief Get the value of an information element that has a raw payload
00405  *
00406  * \param event The event to get the IE from
00407  * \param ie_type the type of information element to retrieve
00408  * 
00409  * \return This returns the payload of the information element with the given type.
00410  *         If the information element isn't found, NULL will be returned.
00411  */
00412 const void *ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_ie_type ie_type);
00413 
00414 /*!
00415  * \brief Get the type for an event
00416  *
00417  * \param event the event to get the type for
00418  *
00419  * \return the event type as represented by one of the values in the
00420  *         ast_event_type enum
00421  */
00422 enum ast_event_type ast_event_get_type(const struct ast_event *event);
00423 
00424 /*!
00425  * \brief Initialize an event iterator instance
00426  *
00427  * \param iterator The iterator instance to initialize
00428  * \param event The event that will be iterated through
00429  *
00430  * \return Nothing
00431  */
00432 void ast_event_iterator_init(struct ast_event_iterator *iterator, const struct ast_event *event);
00433 
00434 /*!
00435  * \brief Move iterator instance to next IE
00436  *
00437  * \param iterator The iterator instance
00438  *
00439  * \retval 0 on success
00440  * \retval -1 if end is reached
00441  */
00442 int ast_event_iterator_next(struct ast_event_iterator *iterator);
00443 
00444 /*!
00445  * \brief Get the type of the current IE in the iterator instance
00446  *
00447  * \param iterator The iterator instance
00448  *
00449  * \return the ie type as represented by one of the value sin the
00450  *         ast_event_ie_type enum
00451  */
00452 enum ast_event_ie_type ast_event_iterator_get_ie_type(struct ast_event_iterator *iterator);
00453 
00454 /*!
00455  * \brief Get the value of the current IE in the ierator as an integer payload
00456  *
00457  * \param iterator The iterator instance
00458  *
00459  * \return This returns the payload of the information element as a uint.
00460  */
00461 uint32_t ast_event_iterator_get_ie_uint(struct ast_event_iterator *iterator);
00462 
00463 /*!
00464  * \brief Get the value of the current IE in the iterator as a string payload
00465  *
00466  * \param iterator The iterator instance
00467  *
00468  * \return This returns the payload of the information element as a string.
00469  */
00470 const char *ast_event_iterator_get_ie_str(struct ast_event_iterator *iterator);
00471 
00472 /*!
00473  * \brief Get the value of the current IE in the iterator instance that has a raw payload
00474  *
00475  * \param iterator The iterator instance
00476  *
00477  * \return This returns the payload of the information element as type raw.
00478  */
00479 void *ast_event_iterator_get_ie_raw(struct ast_event_iterator *iterator);
00480 
00481 #if defined(__cplusplus) || defined(c_plusplus)
00482 }
00483 #endif
00484 
00485 #endif /* AST_EVENT_H */

Generated on Thu Jul 9 13:40:33 2009 for Asterisk - the Open Source PBX by  doxygen 1.4.7