diff options
Diffstat (limited to 'include/asterisk/event.h')
| -rw-r--r-- | include/asterisk/event.h | 91 |
1 files changed, 54 insertions, 37 deletions
diff --git a/include/asterisk/event.h b/include/asterisk/event.h index 45d10fc73..96cf9bd0a 100644 --- a/include/asterisk/event.h +++ b/include/asterisk/event.h @@ -63,7 +63,7 @@ extern "C" { #include "asterisk/event_defs.h" -/*! +/*! * \brief Subscriber event callback type * * \param event the event being passed to the subscriber @@ -73,7 +73,7 @@ extern "C" { */ 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 @@ -110,45 +110,48 @@ typedef void (*ast_event_cb_t)(const struct ast_event *event, void *userdata); * 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, +struct ast_event_sub *ast_event_subscribe(enum ast_event_type event_type, ast_event_cb_t cb, void *userdata, ...); /*! * \brief Allocate a subscription, but do not activate it * - * \arg type the event type to subscribe to - * \arg cb the function to call when an event matches this subscription - * \arg userdata data to pass to the provided callback + * \param type the event type to subscribe to + * \param cb the function to call when an event matches this subscription + * \param userdata data to pass to the provided callback * * This function should be used when you want to dynamically build a * subscription. * * \return the allocated subscription, or NULL on failure + * \since 1.6.1 */ -struct ast_event_sub *ast_event_subscribe_new(enum ast_event_type type, +struct ast_event_sub *ast_event_subscribe_new(enum ast_event_type type, ast_event_cb_t cb, void *userdata); /*! * \brief Destroy an allocated subscription * - * \arg sub the subscription to destroy + * \param sub the subscription to destroy * * This function should be used when a subscription is allocated with * ast_event_subscribe_new(), but for some reason, you want to destroy it * instead of activating it. This could be because of an error when * reading in the configuration for the dynamically built subscription. + * \since 1.6.1 */ void ast_event_sub_destroy(struct ast_event_sub *sub); /*! * \brief Append a uint parameter to a subscription * - * \arg sub the dynamic subscription allocated with ast_event_subscribe_new() - * \arg ie_type the information element type for the parameter - * \arg uint the value that must be present in the event to match this subscription + * \param sub the dynamic subscription allocated with ast_event_subscribe_new() + * \param ie_type the information element type for the parameter + * \param uint the value that must be present in the event to match this subscription * * \retval 0 success * \retval non-zero failure + * \since 1.6.1 */ int ast_event_sub_append_ie_uint(struct ast_event_sub *sub, enum ast_event_ie_type ie_type, uint32_t uint); @@ -156,53 +159,57 @@ int ast_event_sub_append_ie_uint(struct ast_event_sub *sub, /*! * \brief Append a string parameter to a subscription * - * \arg sub the dynamic subscription allocated with ast_event_subscribe_new() - * \arg ie_type the information element type for the parameter - * \arg str the string that must be present in the event to match this subscription + * \param sub the dynamic subscription allocated with ast_event_subscribe_new() + * \param ie_type the information element type for the parameter + * \param str the string that must be present in the event to match this subscription * * \retval 0 success * \retval non-zero failure + * \since 1.6.1 */ -int ast_event_sub_append_ie_str(struct ast_event_sub *sub, +int ast_event_sub_append_ie_str(struct ast_event_sub *sub, enum ast_event_ie_type ie_type, const char *str); /*! * \brief Append a raw parameter to a subscription * - * \arg sub the dynamic subscription allocated with ast_event_subscribe_new() - * \arg ie_type the information element type for the parameter - * \arg raw the data that must be present in the event to match this subscription + * \param sub the dynamic subscription allocated with ast_event_subscribe_new() + * \param ie_type the information element type for the parameter + * \param raw the data that must be present in the event to match this subscription * * \retval 0 success * \retval non-zero failure + * \since 1.6.1 */ -int ast_event_sub_append_ie_raw(struct ast_event_sub *sub, +int ast_event_sub_append_ie_raw(struct ast_event_sub *sub, enum ast_event_ie_type ie_type, void *data, size_t raw_datalen); /*! * \brief Append an 'exists' parameter to a subscription * - * \arg sub the dynamic subscription allocated with ast_event_subscribe_new() - * \arg ie_type the information element type that must be present in the event + * \param sub the dynamic subscription allocated with ast_event_subscribe_new() + * \param ie_type the information element type that must be present in the event * for it to match this subscription. * * \retval 0 success * \retval non-zero failure + * \since 1.6.1 */ -int ast_event_sub_append_ie_exists(struct ast_event_sub *sub, +int ast_event_sub_append_ie_exists(struct ast_event_sub *sub, enum ast_event_ie_type ie_type); /*! * \brief Activate a dynamically built subscription * - * \arg sub the subscription to activate that was allocated using + * \param sub the subscription to activate that was allocated using * ast_event_subscribe_new() * - * Once a dynamically built subscription has had all of the parameters added + * Once a dynamically built subscription has had all of the parameters added * to it, it should be activated using this function. * * \retval 0 success * \retval non-zero failure + * \since 1.6.1 */ int ast_event_sub_activate(struct ast_event_sub *sub); @@ -216,6 +223,7 @@ int ast_event_sub_activate(struct ast_event_sub *sub); * structures. * * \return NULL for convenience. + * \version 1.6.1 return changed to NULL */ struct ast_event_sub *ast_event_unsubscribe(struct ast_event_sub *event_sub); @@ -252,7 +260,7 @@ struct ast_event_sub *ast_event_unsubscribe(struct ast_event_sub *event_sub); * } * \endcode * - * This example will check if there are any subscribers to MWI events for the + * 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, ...); @@ -274,7 +282,10 @@ enum ast_event_subscriber_res ast_event_check_subscriber(enum ast_event_type eve */ void ast_event_report_subs(const struct ast_event_sub *sub); -/*! \brief Dump the event cache for the subscriber */ +/*! + * \brief Dump the event cache for the subscriber + * \since 1.6.1 + */ void ast_event_dump_cache(const struct ast_event_sub *event_sub); /*! @@ -337,7 +348,7 @@ void ast_event_destroy(struct ast_event *event); * * 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 + * dispatched because a pool of event dispatching threads handle the event * queue. */ int ast_event_queue(struct ast_event *event); @@ -350,7 +361,7 @@ int ast_event_queue(struct ast_event *event); * 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 cache and then this one will be added. The arguments are specified in * the form: * * \code @@ -481,7 +492,7 @@ int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_ * * \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. @@ -493,7 +504,7 @@ uint32_t ast_event_get_ie_uint(const struct ast_event *event, enum ast_event_ie_ * * \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. */ @@ -504,7 +515,7 @@ const char *ast_event_get_ie_str(const struct ast_event *event, enum ast_event_i * * \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. */ @@ -513,18 +524,20 @@ const void *ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_i /*! * \brief Get the string representation of an information element type * - * \arg ie_type the information element type to get the string representation of + * \param ie_type the information element type to get the string representation of * * \return the string representation of the information element type + * \since 1.6.1 */ const char *ast_event_get_ie_type_name(enum ast_event_ie_type ie_type); /*! * \brief Get the payload type for a given information element type * - * \arg ie_type the information element type to get the payload type of + * \param ie_type the information element type to get the payload type of * * \return the payload type for the provided IE type + * \since 1.6.1 */ enum ast_event_ie_pltype ast_event_get_ie_pltype(enum ast_event_ie_type ie_type); @@ -544,28 +557,31 @@ enum ast_event_type ast_event_get_type(const struct ast_event *event); * \arg event the event to get the type of * * \return the string representation of the event type of the provided event + * \since 1.6.1 */ const char *ast_event_get_type_name(const struct ast_event *event); /*! * \brief Convert a string into an event type * - * \arg str the string to convert - * \arg event_type an output parameter for the event type + * \param str the string to convert + * \param event_type an output parameter for the event type * * \retval 0 success * \retval non-zero failure + * \since 1.6.1 */ int ast_event_str_to_event_type(const char *str, enum ast_event_type *event_type); /*! * \brief Convert a string to an IE type * - * \arg str the string to convert - * \arg ie_type an output parameter for the IE type + * \param str the string to convert + * \param ie_type an output parameter for the IE type * * \retval 0 success * \retval non-zero failure + * \since 1.6.1 */ int ast_event_str_to_ie_type(const char *str, enum ast_event_ie_type *ie_type); @@ -575,6 +591,7 @@ int ast_event_str_to_ie_type(const char *str, enum ast_event_ie_type *ie_type); * \param event the event to get the size of * * \return the number of bytes contained in the event + * \since 1.6.1 */ size_t ast_event_get_size(const struct ast_event *event); |