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

[asterisk-commits at lists.digium.com]

Author: russell
Date: Wed Mar 28 18:03:02 2007
New Revision: 59297

URL: http://svn.digium.com/view/asterisk?view=rev&rev=59297
Log:
Document a few more functions of the event 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=59297&r1=59296&r2=59297
==============================================================================
--- team/russell/events/include/asterisk/event.h (original)
+++ team/russell/events/include/asterisk/event.h Wed Mar 28 18:03:02 2007
@@ -125,13 +125,108 @@
  */
 enum ast_event_subscriber_res ast_event_check_subscriber(enum ast_event_type event_type, ...);
 
-struct ast_event *ast_event_new(enum ast_event_type, ...);
-
-void ast_event_destroy(struct ast_event *);
-
-int ast_event_queue(struct ast_event *);
-
-int ast_event_queue_and_cache(struct ast_event *, ...);
+/*!
+ * \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;
+ * }
+ * \code
+ *
+ * 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.
+ */
+int ast_event_queue(struct ast_event *event);
+
+/*!
+ * \brief Queue and cache an event
+ *
+ * \param event the event to be queued and cached
+ *
+ * The rest of the arguments to this function specify information elements to
+ * use for determining which events in the cache that this event should replace.
+ * All events in the cache that match the specified criteria will be removed from
+ * the cache and then this one will be added.  The arguments are specified in 
+ * the form:
+ *
+ * \code
+ *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype]
+ * \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 given is EXISTS, then all
+ * events that contain that information element will be removed from the cache.
+ * Otherwise, all events in the cache that contain an information element with
+ * the same value as the new event will be removed.
+ *
+ * \note If more than one IE parameter is specified, they *all* must match for
+ *       the event to be removed from the cache.
+ *
+ * Example usage:
+ *
+ * \code
+ * ast_event_queue_and_cache(event,
+ *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR,
+ *     AST_EVENT_IE_END);
+ * \endcode
+ *
+ * This example queues and caches an event.  Any events in the cache that have
+ * the same MAILBOX information element as this event will be removed.
+ */
+int ast_event_queue_and_cache(struct ast_event *event, ...);
 
 struct ast_event *ast_event_get_cached(enum ast_event_type, ...);