[svn-commits] russell: branch russell/event_performance r183987 - /team/russell/event_perfo...

[SVN commits to the Digium repositories]

Author: russell
Date: Tue Mar 24 12:57:19 2009
New Revision: 183987

URL: http://svn.digium.com/svn-view/asterisk?view=rev&rev=183987
Log:
update docs for queue_and_cache()

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

Modified: team/russell/event_performance/include/asterisk/event.h
URL: http://svn.digium.com/svn-view/asterisk/team/russell/event_performance/include/asterisk/event.h?view=diff&rev=183987&r1=183986&r2=183987
==============================================================================
--- team/russell/event_performance/include/asterisk/event.h (original)
+++ team/russell/event_performance/include/asterisk/event.h Tue Mar 24 12:57:19 2009
@@ -358,42 +358,18 @@
  *
  * \param event the event to be queued and cached
  *
+ * \details
  * 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.
  *
  * The purpose of caching events is so that the core can retain the last known
  * information for events that represent some sort of state.  That way, when
  * code needs to find out the current state, it can query the cache.
  *
- * XXX FIX DOCS XXX
+ * The event API already knows which events can be cached and how to cache them.
+ *
+ * \retval 0 success
+ * \retval non-zero failure.  If failure is returned, the event must be destroyed
+ *         by the caller of this function.
  */
 int ast_event_queue_and_cache(struct ast_event *event);