event.h

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

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.
 *
 * 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.
 */
int ast_event_queue_and_cache(struct ast_event *event, ...);

/*!
 * \brief Retrieve an event from the cache
 *
 * \param ast_event_type The type of event to retrieve from the cache
 *
 * The rest of the arguments to this function specify information elements to
 * match for retrieving events from the cache.  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.  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 A reference to an event retrieved from the cache.  If no event was
 *         found that matches the specified criteria, then NULL will be returned.
 *
 * \note If more than one event in the cache matches the specified criteria, only
 *       one will be returned, and it is undefined which one it will be.
 *
 * \note The caller of this function *must* call ast_event_destroy() on the
 *       returned event after it is done using it.
 *
 * Example Usage:
 *
 * \code
 * event = ast_event_get_cached(AST_EVENT_MWI,
 *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox,
 *     AST_EVENT_IE_END);
 * \endcode
 *
 * This example will check for an MWI event in the cache that matches the
 * specified mailbox.  This would be the way to find out the last known state
 * of a mailbox without having to poll the mailbox directly.
 */
struct ast_event *ast_event_get_cached(enum ast_event_type, ...);

/*!
 * \brief Append an information element that has a string payload
 *
 * \param event the event that the IE will be appended to
 * \param ie_type the type of IE to append
 * \param str The string for the payload of the IE
 *
 * \retval 0 success
 * \retval -1 failure
 *
 * The pointer to the event will get updated with the new location for the event
 * that now contains the appended information element.  If the re-allocation of
 * the memory for this event fails, it will be set to NULL.
 */
int ast_event_append_ie_str(struct ast_event **event, enum ast_event_ie_type ie_type,
	const char *str);

/*!
 * \brief Append an information element that has an integer payload
 *
 * \param event the event that the IE will be appended to
 * \param ie_type the type of IE to append
 * \param data The integer for the payload of the IE
 *
 * \retval 0 success
 * \retval -1 failure
 *
 * The pointer to the event will get updated with the new location for the event
 * that now contains the appended information element.  If the re-allocation of
 * the memory for this event fails, it will be set to NULL.
 */
int ast_event_append_ie_uint(struct ast_event **event, enum ast_event_ie_type ie_type,
	uint32_t data);

/*!
 * \brief Append an information element that has a raw payload
 *
 * \param event the event that the IE will be appended to
 * \param ie_type the type of IE to append
 * \param data A pointer to the raw data for the payload of the IE
 * \param data_len The amount of data to copy into the payload
 *
 * \retval 0 success
 * \retval -1 failure
 *
 * The pointer to the event will get updated with the new location for the event
 * that now contains the appended information element.  If the re-allocation of
 * the memory for this event fails, it will be set to NULL.
 */
int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_type,
	const void *data, size_t data_len);

/*!
 * \brief Get the value of an information element that has an integer payload
 *
 * \param event The event to get the IE from
 * \param ie_type the type of information element to retrieve
 * 
 * \return This returns the payload of the information element with the given type.
 *         However, an IE with a payload of 0, and the case where no IE is found
 *         yield the same return value.
 */
uint32_t ast_event_get_ie_uint(const struct ast_event *event, enum ast_event_ie_type ie_type);

/*!
 * \brief Get the value of an information element that has a string payload
 *
 * \param event The event to get the IE from
 * \param ie_type the type of information element to retrieve
 * 
 * \return This returns the payload of the information element with the given type.
 *         If the information element isn't found, NULL will be returned.
 */
const char *ast_event_get_ie_str(const struct ast_event *event, enum ast_event_ie_type ie_type);

/*!
 * \brief Get the value of an information element that has a raw payload
 *
 * \param event The event to get the IE from
 * \param ie_type the type of information element to retrieve
 * 
 * \return This returns the payload of the information element with the given type.
 *         If the information element isn't found, NULL will be returned.
 */
const void *ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_ie_type ie_type);

/*!
 * \brief Get the type for an event
 *
 * \param event the event to get the type for
 *
 * \return the event type as represented by one of the values in the
 *         ast_event_type enum
 */
enum ast_event_type ast_event_get_type(const struct ast_event *event);

/*!
 * \brief Initialize an event iterator instance
 *
 * \param iterator The iterator instance to initialize
 * \param event The event that will be iterated through
 *
 * \return Nothing
 */
void ast_event_iterator_init(struct ast_event_iterator *iterator, const struct ast_event *event);

/*!
 * \brief Move iterator instance to next IE
 *
 * \param iterator The iterator instance
 *
 * \retval 0 on success
 * \retval -1 if end is reached
 */
int ast_event_iterator_next(struct ast_event_iterator *iterator);

/*!
 * \brief Get the type of the current IE in the iterator instance
 *
 * \param iterator The iterator instance
 *
 * \return the ie type as represented by one of the value sin the
 *         ast_event_ie_type enum
 */
enum ast_event_ie_type ast_event_iterator_get_ie_type(struct ast_event_iterator *iterator);

/*!
 * \brief Get the value of the current IE in the ierator as an integer payload
 *
 * \param iterator The iterator instance
 *
 * \return This returns the payload of the information element as a uint.
 */
uint32_t ast_event_iterator_get_ie_uint(struct ast_event_iterator *iterator);

/*!
 * \brief Get the value of the current IE in the iterator as a string payload
 *
 * \param iterator The iterator instance
 *
 * \return This returns the payload of the information element as a string.
 */
const char *ast_event_iterator_get_ie_str(struct ast_event_iterator *iterator);

/*!
 * \brief Get the value of the current IE in the iterator instance that has a raw payload
 *
 * \param iterator The iterator instance
 *
 * \return This returns the payload of the information element as type raw.
 */
void *ast_event_iterator_get_ie_raw(struct ast_event_iterator *iterator);

#if defined(__cplusplus) || defined(c_plusplus)
}
#endif

#endif /* AST_EVENT_H */