[asterisk-commits] russell: branch russell/events r62287 - /team/russell/events/include/asterisk/

[asterisk-commits at lists.digium.com]

Author: russell
Date: Sat Apr 28 15:23:58 2007
New Revision: 62287

URL: http://svn.digium.com/view/asterisk?view=rev&rev=62287
Log:
Add a more verbose explanation of the purpose of this API

Modified:
    team/russell/events/include/asterisk/event.h

Modified: team/russell/events/include/asterisk/event.h
URL: http://svn.digium.com/view/asterisk/team/russell/events/include/asterisk/event.h?view=diff&rev=62287&r1=62286&r2=62287
==============================================================================
--- team/russell/events/include/asterisk/event.h (original)
+++ team/russell/events/include/asterisk/event.h Sat Apr 28 15:23:58 2007
@@ -20,6 +20,34 @@
  * \file
  * \author Russell Bryant <russell at digium.com>
  * \brief 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 containts 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