diff options
Diffstat (limited to 'include/asterisk')
| -rw-r--r-- | include/asterisk/event.h | 165 | ||||
| -rw-r--r-- | include/asterisk/event_defs.h | 57 |
2 files changed, 203 insertions, 19 deletions
diff --git a/include/asterisk/event.h b/include/asterisk/event.h index 01fc833ba..45d10fc73 100644 --- a/include/asterisk/event.h +++ b/include/asterisk/event.h @@ -1,7 +1,7 @@ /* * Asterisk -- An open source telephony toolkit. * - * Copyright (C) 2007, Digium, Inc. + * Copyright (C) 2007 - 2008, Digium, Inc. * * Russell Bryant <russell@digium.com> * @@ -114,14 +114,110 @@ 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 + * + * This function should be used when you want to dynamically build a + * subscription. + * + * \return the allocated subscription, or NULL on failure + */ +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 + * + * 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. + */ +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 + * + * \retval 0 success + * \retval non-zero failure + */ +int ast_event_sub_append_ie_uint(struct ast_event_sub *sub, + enum ast_event_ie_type ie_type, uint32_t uint); + +/*! + * \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 + * + * \retval 0 success + * \retval non-zero failure + */ +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 + * + * \retval 0 success + * \retval non-zero failure + */ +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 + * for it to match this subscription. + * + * \retval 0 success + * \retval non-zero failure + */ +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 + * ast_event_subscribe_new() + * + * 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 + */ +int ast_event_sub_activate(struct ast_event_sub *sub); + +/*! * \brief Un-subscribe from events * * \param event_sub This is the reference to the subscription returned by * ast_event_subscribe. - * - * \return Nothing + * + * This function will remove a subscription and free the associated data + * structures. + * + * \return NULL for convenience. */ -void ast_event_unsubscribe(struct ast_event_sub *event_sub); +struct ast_event_sub *ast_event_unsubscribe(struct ast_event_sub *event_sub); /*! * \brief Check if subscribers exist @@ -178,6 +274,9 @@ 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 */ +void ast_event_dump_cache(const struct ast_event_sub *event_sub); + /*! * \brief Create a new event * @@ -412,6 +511,24 @@ const char *ast_event_get_ie_str(const struct ast_event *event, enum ast_event_i const void *ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_ie_type ie_type); /*! + * \brief Get the string representation of an information element type + * + * \arg ie_type the information element type to get the string representation of + * + * \return the string representation of the information element type + */ +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 + * + * \return the payload type for the provided IE type + */ +enum ast_event_ie_pltype ast_event_get_ie_pltype(enum ast_event_ie_type ie_type); + +/*! * \brief Get the type for an event * * \param event the event to get the type for @@ -422,6 +539,46 @@ const void *ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_i enum ast_event_type ast_event_get_type(const struct ast_event *event); /*! + * \brief Get the string representation of the type of the given event + * + * \arg event the event to get the type of + * + * \return the string representation of the event type of the provided event + */ +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 + * + * \retval 0 success + * \retval non-zero failure + */ +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 + * + * \retval 0 success + * \retval non-zero failure + */ +int ast_event_str_to_ie_type(const char *str, enum ast_event_ie_type *ie_type); + +/*! + * \brief Get the size of an event + * + * \param event the event to get the size of + * + * \return the number of bytes contained in the event + */ +size_t ast_event_get_size(const struct ast_event *event); + +/*! * \brief Initialize an event iterator instance * * \param iterator The iterator instance to initialize diff --git a/include/asterisk/event_defs.h b/include/asterisk/event_defs.h index b664ac14b..3f1e3bd15 100644 --- a/include/asterisk/event_defs.h +++ b/include/asterisk/event_defs.h @@ -1,7 +1,7 @@ /* * Asterisk -- An open source telephony toolkit. * - * Copyright (C) 2007, Digium, Inc. + * Copyright (C) 2007 - 2008, Digium, Inc. * * Russell Bryant <russell@digium.com> * @@ -29,23 +29,27 @@ * \note These values can *never* change. */ enum ast_event_type { /*! Reserved to provide the ability to subscribe to all events. A specific - event should never have a payload of 0. */ - AST_EVENT_ALL = 0x00, + * event should never have a payload of 0. */ + AST_EVENT_ALL = 0x00, /*! This event type is reserved for use by third-party modules to create - custom events without having to modify this file. - \note There are no "custom" IE types, because IEs only have to be - unique to the event itself, not necessarily across all events. */ - AST_EVENT_CUSTOM = 0x01, + * custom events without having to modify this file. + * \note There are no "custom" IE types, because IEs only have to be + * unique to the event itself, not necessarily across all events. */ + AST_EVENT_CUSTOM = 0x01, /*! Voicemail message waiting indication */ - AST_EVENT_MWI = 0x02, + AST_EVENT_MWI = 0x02, /*! Someone has subscribed to events */ - AST_EVENT_SUB = 0x03, + AST_EVENT_SUB = 0x03, /*! Someone has unsubscribed from events */ - AST_EVENT_UNSUB = 0x04, - /*! The state of a device has changed */ - AST_EVENT_DEVICE_STATE = 0x05, + AST_EVENT_UNSUB = 0x04, + /*! The aggregate state of a device across all servers configured to be + * a part of a device state cluster has changed. */ + AST_EVENT_DEVICE_STATE = 0x05, + /*! The state of a device has changed on _one_ server. This should not be used + * directly, in general. Use AST_EVENT_DEVICE_STATE instead. */ + AST_EVENT_DEVICE_STATE_CHANGE = 0x06, /*! Number of event types. This should be the last event type + 1 */ - AST_EVENT_TOTAL = 0x06, + AST_EVENT_TOTAL = 0x07, }; /*! \brief Event Information Element types */ @@ -91,13 +95,13 @@ enum ast_event_ie_type { AST_EVENT_IE_EXISTS = 0x06, /*! * \brief Device Name - * Used by AST_EVENT_DEVICE_STATE + * Used by AST_EVENT_DEVICE_STATE_CHANGE * Payload type: STR */ AST_EVENT_IE_DEVICE = 0x07, /*! * \brief Generic State IE - * Used by AST_EVENT_DEVICE_STATE + * Used by AST_EVENT_DEVICE_STATE_CHANGE * Payload type: UINT * The actual state values depend on the event which * this IE is a part of. @@ -109,18 +113,30 @@ enum ast_event_ie_type { * Payload type: str */ AST_EVENT_IE_CONTEXT = 0x09, + /*! + * \brief Entity ID + * Used by All events + * Payload type: RAW + * This IE indicates which server the event originated from + */ + AST_EVENT_IE_EID = 0x0A, }; +#define AST_EVENT_IE_MAX AST_EVENT_IE_EID + /*! * \brief Payload types for event information elements */ enum ast_event_ie_pltype { + AST_EVENT_IE_PLTYPE_UNKNOWN = -1, /*! Just check if it exists, not the value */ AST_EVENT_IE_PLTYPE_EXISTS, /*! Unsigned Integer (Can be used for signed, too ...) */ AST_EVENT_IE_PLTYPE_UINT, /*! String */ AST_EVENT_IE_PLTYPE_STR, + /*! Raw data, compared with memcmp */ + AST_EVENT_IE_PLTYPE_RAW, }; /*! @@ -140,4 +156,15 @@ struct ast_event_ie; struct ast_event_sub; struct ast_event_iterator; +/*! + * \brief supposed to be an opaque type + * + * This is only here so that it can be declared on the stack. + */ +struct ast_event_iterator { + uint16_t event_len; + const struct ast_event *event; + struct ast_event_ie *ie; +}; + #endif /* AST_EVENT_DEFS_H */ |