event.h

asterisk 是一个很有知名度开源软件

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2007, Digium, Inc.
 *
 * Russell Bryant <[e-mail]>
 *
 * See http://www.asterisk.org for more information about
 * the Asterisk project. Please do not directly contact
 * any of the maintainers of this project for assistance;
 * the project provides a web site, mailing lists and IRC
 * channels for your use.
 *
 * This program is free software, distributed under the terms of
 * the GNU General Public License Version 2. See the LICENSE file
 * at the top of the source tree.
 */

/*!
 * \file
 * \author Russell Bryant <[e-mail]>
 * \ref AstGenericEvents
 */

/*!
 * \page AstGenericEvents Generic event system
 *
 * The purpose of this API is to provide a generic way to share events between
 * Asterisk modules.  Code can generate events, and other code can subscribe to
 * them.
 *
 * Events have an associated event type, as well as information elements.  The
 * information elements are the meta data that go along with each event.  For
 * example, in the case of message waiting indication, the event type is MWI,
 * and each MWI event contains at least three information elements: the
 * mailbox, the number of new messages, and the number of old messages.
 *
 * Subscriptions to events consist of an event type and information elements,
 * as well.  Subscriptions can be to all events, or a certain subset of events.
 * If an event type is provided, only events of that type will be sent to this
 * subscriber.  Furthermore, if information elements are supplied with the
 * subscription, only events that contain the specified information elements
 * with specified values will be sent to the subscriber.  For example, when a
 * SIP phone subscribes to MWI for mailbox 1234, then chan_sip can subscribe
 * to internal Asterisk MWI events with the MAILBOX information element with
 * a value of "1234".
 *
 * Another key feature of this event system is the ability to cache events.
 * It is useful for some types of events to be able to remember the last known
 * value.  These are usually events that indicate some kind of state change.
 * In the example of MWI, app_voicemail can instruct the event core to cache
 * these events based on the mailbox.  So, the last known MWI state of each
 * mailbox will be cached, and other modules can retrieve this information
 * on demand without having to poll the mailbox directly.
 */

#ifndef AST_EVENT_H
#define AST_EVENT_H

#if defined(__cplusplus) || defined(c_plusplus)
extern "C" {
#endif

#include "asterisk/event_defs.h"

/*! 
 * \brief Subscriber event callback type
 *
 * \param event the event being passed to the subscriber
 * \param userdata the data provider in the call to ast_event_subscribe()
 *
 * \return The event callbacks do not return anything.
 */
typedef void (*ast_event_cb_t)(const struct ast_event *event, void *userdata);

/*! 
 * \brief Subscribe to events
 *
 * \param event_type The type of events to subscribe to
 * \param cb The function to be called with events
 * \param userdata data to be passed to the event callback
 *
 * The rest of the arguments to this function specify additional parameters for
 * the subscription to filter which events are passed to this subscriber.  The
 * arguments must be in sets of:
 * \code
 *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
 * \endcode
 * and must end with AST_EVENT_IE_END.
 *
 * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
 * by a valid IE payload type.  If the payload type specified is
 * AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided.
 * Otherwise, a payload must also be specified.
 *
 * \return This returns a reference to the subscription for use with
 *         un-subscribing later.  If there is a failure in creating the
 *         subscription, NULL will be returned.
 *
 * Example usage:
 *
 * \code
 * peer->mwi_event_sub = ast_event_subscribe(AST_EVENT_MWI, mwi_event_cb, peer,
 *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, peer->mailbox,
 *     AST_EVENT_IE_END);
 * \endcode
 *
 * This creates a subscription to AST_EVENT_MWI events that contain an
 * information element, AST_EVENT_IE_MAILBOX, with the same string value
 * contained in peer->mailbox.  Also, the event callback will be passed a
 * pointer to the peer.
 */
struct ast_event_sub *ast_event_subscribe(enum ast_event_type event_type, 
	ast_event_cb_t cb, void *userdata, ...);

/*!
 * \brief Un-subscribe from events
 *
 * \param event_sub This is the reference to the subscription returned by
 *        ast_event_subscribe.
 * 
 * \return Nothing
 */
void ast_event_unsubscribe(struct ast_event_sub *event_sub);

/*!
 * \brief Check if subscribers exist
 *
 * \param event_type This is the type of event that the caller would like to
 *        check for subscribers to.
 *
 * The rest of the arguments to this function specify additional parameters for
 * checking for subscriptions to subsets of an event type. The arguments must
 * in sets of:
 * \code
 *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
 * \endcode
 * and must end with AST_EVENT_IE_END.
 *
 * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
 * by a valid IE payload type.  If the payload type specified is
 * AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided.
 * Otherwise, a payload must also be specified.
 *
 * \return This returns one of the values defined in the ast_event_subscriber_res
 *         enum which will indicate if subscribers exist that match the given
 *         criteria.
 *
 * Example usage:
 *
 * \code
 * if (ast_event_check_subscriber(AST_EVENT_MWI,
 *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox,
 *     AST_EVENT_IE_END) == AST_EVENT_SUB_NONE) {
 *       return;
 * }
 * \endcode
 *
 * This example will check if there are any subscribers to MWI events for the 
 * mailbox defined in the "mailbox" variable.
 */
enum ast_event_subscriber_res ast_event_check_subscriber(enum ast_event_type event_type, ...);

/*!
 * \brief Report current subscriptions to a subscription subscriber
 *
 * \arg sub the subscription subscriber
 *
 * \return nothing
 *
 * This reports all of the current subscribers to a subscriber of
 * subscribers to a specific event type.  (Try saying that a few times fast).
 *
 * The idea here is that it is sometimes very useful for a module to know when
 * someone subscribes to events.  However, when they first subscribe, this
 * provides that module the ability to request the event core report to them
 * all of the subscriptions to that event type that already exist.
 */
void ast_event_report_subs(const struct ast_event_sub *sub);

/*!
 * \brief Create a new event
 *
 * \param event_type The type of event to create
 *
 * The rest of the arguments to this function specify information elements to
 * add to the event.  They are specified in the form:
 * \code
 *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
 * \endcode
 * and must end with AST_EVENT_IE_END.
 *
 * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
 * by a valid IE payload type.  The payload type, EXISTS, should not be used here
 * because it makes no sense to do so.  So, a payload must also be specified
 * after the IE payload type.
 *
 * \return This returns the event that has been created.  If there is an error
 *         creating the event, NULL will be returned.
 *
 * Example usage:
 *
 * \code
 * if (!(event = ast_event_new(AST_EVENT_MWI,
 *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox,
 *     AST_EVENT_IE_NEWMSGS, AST_EVENT_IE_PLTYPE_UINT, new,
 *     AST_EVENT_IE_OLDMSGS, AST_EVENT_IE_PLTYPE_UINT, old,
 *     AST_EVENT_IE_END))) {
 *       return;
 * }
 * \endcode
 *
 * This creates a MWI event with 3 information elements, a mailbox which is
 * a string, and the number of new and old messages, specified as integers.
 */
struct ast_event *ast_event_new(enum ast_event_type event_type, ...);

/*!
 * \brief Destroy an event
 *
 * \param event the event to destroy
 *
 * \return Nothing
 *
 * \note Events that have been queued should *not* be destroyed by the code that
 *       created the event.  It will be automatically destroyed after being
 *       dispatched to the appropriate subscribers.
 */
void ast_event_destroy(struct ast_event *event);

/*!
 * \brief Queue an event
 *
 * \param event the event to be queued
 *
 * \retval zero success
 * \retval non-zero failure
 *
 * This function queues an event to be dispatched to all of the appropriate
 * subscribers.  This function will not block while the event is being
 * dispatched because a pool of event dispatching threads handle the event 
 * queue.
 */