Remove required type field from channel blobs

When we first introduced the channel blob types, the JSON blobs were
self identifying by a required "type" field in the JSON object
itself. This, as it turns out, was a bad idea.

When we introduced the message router, it was useless for routing based
on the JSON type. And messages had two type fields to check: the
stasis_message_type() of the message itself, plus the type field in the
JSON blob (but only if it was a blob message).

This patch corrects that mistake by removing the required type field
from JSON blobs, and introducing first class stasis_message_type objects
for the actual message type.

Since we now will have a proliferation of message types, I introduced a
few macros to help reduce the amount of boilerplate necessary to set
them up.

Review: https://reviewboard.asterisk.org/r/2509


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

2 files changed, 95 insertions, 50 deletions

diff --git a/include/asterisk/stasis.h b/include/asterisk/stasis.h
index 48d51e369..da8168746 100644
--- a/include/asterisk/stasis.h
+++ b/include/asterisk/stasis.h
@@ -543,6 +543,43 @@ struct ao2_container *stasis_cache_dump(struct stasis_caching_topic *caching_top
 /*! @{ */
 
 /*!
+ * \brief Boiler-plate removing macro for defining message types.
+ *
+ * \param name Name of message type.
+ * \since 12
+ */
+#define STASIS_MESSAGE_TYPE_DEFN(name)				\
+	static struct stasis_message_type *__ ## name;	\
+	struct stasis_message_type *name(void) {	\
+		ast_assert(__ ## name != NULL);		\
+		return __ ## name;			\
+	}
+
+/*!
+ * \brief Boiler-plate removing macro for initializing message types.
+ *
+ * \param name Name of message type.
+ * \return 0 if initialization is successful.
+ * \return Non-zero on failure.
+ * \since 12
+ */
+#define STASIS_MESSAGE_TYPE_INIT(name)				\
+	({						\
+	__ ## name = stasis_message_type_create(#name);	\
+	__ ## name ? 0 : -1;				\
+	})
+
+#define STASIS_MESSAGE_TYPE_CLEANUP(name)		\
+	({					\
+		ao2_cleanup(__ ## name);	\
+		__ ## name = NULL;		\
+	})
+
+/*! @} */
+
+/*! @{ */
+
+/*!
  * \brief Initialize the Stasis subsystem
  * \return 0 on success.
  * \return Non-zero on error.
diff --git a/include/asterisk/stasis_channels.h b/include/asterisk/stasis_channels.h
index 53dcc24e8..af571eda1 100644
--- a/include/asterisk/stasis_channels.h
+++ b/include/asterisk/stasis_channels.h
@@ -70,8 +70,7 @@ struct ast_channel_snapshot {
  * \since 12
  * \brief Blob of data associated with a channel.
  *
- * The \c blob is actually a JSON object of structured data. It has a "type" field
- * which contains the type string describing this blob.
+ * This blob is actually shared amongst several \ref stasis_message_type's.
  */
 struct ast_channel_blob {
 	/*! Channel blob is associated with (or NULL for global/all channels) */
@@ -112,14 +111,6 @@ struct stasis_message_type *ast_channel_snapshot_type(void);
 
 /*!
  * \since 12
- * \brief Message type for \ref ast_channel_blob messages.
- *
- * \retval Message type for \ref ast_channel_blob messages.
- */
-struct stasis_message_type *ast_channel_blob_type(void);
-
-/*!
- * \since 12
  * \brief Generate a snapshot of the channel state. This is an ao2 object, so
  * ao2_cleanup() to deallocate.
  *
@@ -128,44 +119,35 @@ struct stasis_message_type *ast_channel_blob_type(void);
  * \retval pointer on success (must be ast_freed)
  * \retval NULL on error
  */
-struct ast_channel_snapshot *ast_channel_snapshot_create(struct ast_channel *chan);
+struct ast_channel_snapshot *ast_channel_snapshot_create(
+	struct ast_channel *chan);
 
 /*!
  * \since 12
  * \brief Creates a \ref ast_channel_blob message.
  *
- * The \a blob JSON object requires a \c "type" field describing the blob. It
- * should also be treated as immutable and not modified after it is put into the
- * message.
+ * The given \a blob should be treated as immutable and not modified after it is
+ * put into the message.
+ *
+ * \param chan Channel blob is associated with, or \c NULL for global/all channels.
+ * \param type Message type for this blob.
+ * \param blob JSON object representing the data, or \c NULL for no data. If
+ *             \c NULL, ast_json_null() is put into the object.
  *
- * \param chan Channel blob is associated with, or NULL for global/all channels.
- * \param blob JSON object representing the data.
  * \return \ref ast_channel_blob message.
  * \return \c NULL on error
  */
 struct stasis_message *ast_channel_blob_create(struct ast_channel *chan,
-					       struct ast_json *blob);
-
-/*!
- * \since 12
- * \brief Extracts the type field from a \ref ast_channel_blob.
- * Returned \c char* is still owned by \a obj
- * \param obj Channel blob object.
- * \return Type field value from the blob.
- * \return \c NULL on error.
- */
-const char *ast_channel_blob_json_type(struct ast_channel_blob *obj);
+	struct stasis_message_type *type, struct ast_json *blob);
 
 /*!
  * \since 12
- * \brief Create a \ref ast_multi_channel_blob suitable for a \ref stasis_message
+ * \brief Create a \ref ast_multi_channel_blob suitable for a \ref stasis_message.
  *
- * \note Similar to a \ref ast_channel_blob, the \ref ast_multi_channel_blob requires
- * a \a blob JSON object containing a \c "type" field describing the blob. It
- * should also be treated as immutable and not modified after it is put into the
- * message.
+ * The given \a blob should be treated as immutable and not modified after it is
+ * put into the message.
  *
- * \param blob The JSON blob that defines the type of this \ref ast_multi_channel_blob
+ * \param blob The JSON blob that defines the data of this \ref ast_multi_channel_blob
  *
  * \return \ref ast_multi_channel_blob object
  * \return \c NULL on error
@@ -189,8 +171,7 @@ struct ast_multi_channel_blob *ast_multi_channel_blob_create(struct ast_json *bl
  * \retval NULL on error or not found for the role specified
  */
 struct ast_channel_snapshot *ast_multi_channel_blob_get_channel(
-					       struct ast_multi_channel_blob *obj,
-					       const char *role);
+	struct ast_multi_channel_blob *obj, const char *role);
 
 /*!
  * \since 12
@@ -212,8 +193,7 @@ struct ast_channel_snapshot *ast_multi_channel_blob_get_channel(
  * \retval NULL on error or not found for the role specified
  */
 struct ao2_container *ast_multi_channel_blob_get_channels(
-					       struct ast_multi_channel_blob *obj,
-					       const char *role);
+	struct ast_multi_channel_blob *obj, const char *role);
 
 /*!
  * \since 12
@@ -228,17 +208,6 @@ struct ast_json *ast_multi_channel_blob_get_json(struct ast_multi_channel_blob *
 
 /*!
  * \since 12
- * \brief Extracts the type field from a \ref ast_multi_channel_blob.
- * Returned \c char* is still owned by \a obj
- *
- * \param obj Channel blob object.
- * \return Type field value from the blob.
- * \return \c NULL on error.
- */
-const char *ast_multi_channel_blob_get_type(struct ast_multi_channel_blob *obj);
-
-/*!
- * \since 12
  * \brief Add a \ref ast_channel_snapshot to a \ref ast_multi_channel_blob object
  *
  * \note This will increase the reference count by 1 for the channel snapshot. It is
@@ -250,8 +219,7 @@ const char *ast_multi_channel_blob_get_type(struct ast_multi_channel_blob *obj);
  * \ref ast_multi_channel_blob object
  */
 void ast_multi_channel_blob_add_channel(struct ast_multi_channel_blob *obj,
-					       const char *role,
-					       struct ast_channel_snapshot *snapshot);
+	const char *role, struct ast_channel_snapshot *snapshot);
 
 /*!
  * \since 12
@@ -274,6 +242,46 @@ struct stasis_message_type *ast_channel_dial_type(void);
 
 /*!
  * \since 12
+ * \brief Message type for when a variable is set on a channel.
+ *
+ * \retval A stasis message type
+ */
+struct stasis_message_type *ast_channel_varset_type(void);
+
+/*!
+ * \since 12
+ * \brief Message type for when a custom user event is sent on a channel.
+ *
+ * \retval A stasis message type
+ */
+struct stasis_message_type *ast_channel_user_event_type(void);
+
+/*!
+ * \since 12
+ * \brief Message type for when a hangup is requested on a channel.
+ *
+ * \retval A stasis message type
+ */
+struct stasis_message_type *ast_channel_hangup_request_type(void);
+
+/*!
+ * \since 12
+ * \brief Message type for when DTMF begins on a channel.
+ *
+ * \retval A stasis message type
+ */
+struct stasis_message_type *ast_channel_dtmf_begin_type(void);
+
+/*!
+ * \since 12
+ * \brief Message type for when DTMF ends on a channel.
+ *
+ * \retval A stasis message type
+ */
+struct stasis_message_type *ast_channel_dtmf_end_type(void);
+
+/*!
+ * \since 12
  * \brief Publish in the \ref ast_channel_topic or \ref ast_channel_topic_all
  * topics a stasis message for the channels involved in a dial operation.
  *