Merge some more changes from team/russell/events

This commit pulls in a batch of improvements and additions to the event API.
Changes include:
 - the ability to dynamically build a subscription.  This is useful if you're
    building a subscription based on something you receive from the network,
    or from options in a configuration file.
 - Add tables of event types and IE types and the corresponding string
    representation for implementing text based protocols that use these
	events, for showing events on the CLI, reading configuration that
	references event information, among other things.
 - Add a table that maps IE types and the corresponding payload type.
 - an API call to get the total size of an event
 - an API call to get all events from the cache that match a subscription
 - a new IE payload type, raw, which I used for transporting the Entity ID in
    my code for handling distributed device state.
 - Code improvements to reduce code duplication
 - Include the Entity ID of the server that originated the event in every event
 - an additional event type, DEVICE_STATE_CHANGE, to help facilitate distributed
    device state.  DEVICE_STATE is a state change on one server, DEVICE_STATE_CHANGE
	is the aggregate device state change across all servers.


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@121555 65c4cc65-6c06-0410-ace0-fbb531ad65f3

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 */