Add channel events for res_stasis apps

This change adds a framework in res_stasis for handling events from
channel topics. JSON event generation and validation code is created
from event documentation in rest-api/api-docs/events.json to assist in
JSON event generation, ensure consistency, and ensure that accurate
documentation is available for ALL events that are received by
res_stasis applications.

The userevent application has been refactored along with the code that
handles userevent channel blob events to pass the headers as key/value
pairs in the JSON blob. As a side-effect, app_userevent now handles
duplicate keys by overwriting the previous value.

Review: https://reviewboard.asterisk.org/r/2428/
(closes issue ASTERISK-21180)
Patch-By: Kinsey Moore <kmoore@digium.com>


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

4 files changed, 230 insertions, 32 deletions

diff --git a/res/stasis_http/resource_endpoints.h b/res/stasis_http/resource_endpoints.h
index b534fb047..a0262c064 100644
--- a/res/stasis_http/resource_endpoints.h
+++ b/res/stasis_http/resource_endpoints.h
@@ -83,8 +83,8 @@ void stasis_http_get_endpoint(struct ast_variable *headers, struct ast_get_endpo
  * JSON models
  *
  * Endpoint
+ * - resource: string (required)
  * - technology: string (required)
- * - name: string (required)
  */
 
 #endif /* _ASTERISK_RESOURCE_ENDPOINTS_H */
diff --git a/res/stasis_http/resource_events.h b/res/stasis_http/resource_events.h
index 10799001d..150939d22 100644
--- a/res/stasis_http/resource_events.h
+++ b/res/stasis_http/resource_events.h
@@ -55,42 +55,240 @@ struct ast_event_websocket_args {
  */
 void stasis_http_event_websocket(struct ast_variable *headers, struct ast_event_websocket_args *args, struct stasis_http_response *response);
 
+struct ast_channel_snapshot;
+struct ast_bridge_snapshot;
+
+/*!
+ * \brief Some part of channel state changed.
+ *
+ * \param channel The channel to be used to generate this event
+ *
+ * \retval NULL on error
+ * \retval JSON (ast_json) describing the event
+ */
+struct ast_json *stasis_json_event_channel_snapshot_create(
+	struct ast_channel_snapshot *channel_snapshot
+	);
+
+/*!
+ * \brief Notification that a channel has been destroyed.
+ *
+ * \param channel The channel to be used to generate this event
+ * \param blob JSON blob containing the following parameters:
+ * - cause: integer - Integer representation of the cause of the hangup (required)
+ * - cause_txt: string - Text representation of the cause of the hangup (required)
+ *
+ * \retval NULL on error
+ * \retval JSON (ast_json) describing the event
+ */
+struct ast_json *stasis_json_event_channel_destroyed_create(
+	struct ast_channel_snapshot *channel_snapshot,
+	struct ast_json *blob
+	);
+
+/*!
+ * \brief Channel changed Caller ID.
+ *
+ * \param channel The channel that changed Caller ID.
+ * \param blob JSON blob containing the following parameters:
+ * - caller_presentation_txt: string - The text representation of the Caller Presentation value. (required)
+ * - caller_presentation: integer - The integer representation of the Caller Presentation value. (required)
+ *
+ * \retval NULL on error
+ * \retval JSON (ast_json) describing the event
+ */
+struct ast_json *stasis_json_event_channel_caller_id_create(
+	struct ast_channel_snapshot *channel_snapshot,
+	struct ast_json *blob
+	);
+
+/*!
+ * \brief A hangup was requested on the channel.
+ *
+ * \param channel The channel on which the hangup was requested.
+ * \param blob JSON blob containing the following parameters:
+ * - soft: boolean - Whether the hangup request was a soft hangup request.
+ * - cause: integer - Integer representation of the cause of the hangup.
+ *
+ * \retval NULL on error
+ * \retval JSON (ast_json) describing the event
+ */
+struct ast_json *stasis_json_event_channel_hangup_request_create(
+	struct ast_channel_snapshot *channel_snapshot,
+	struct ast_json *blob
+	);
+
+/*!
+ * \brief Notification that another WebSocket has taken over for an application.
+ *
+ * \param blob JSON blob containing the following parameters:
+ * - application: string  (required)
+ *
+ * \retval NULL on error
+ * \retval JSON (ast_json) describing the event
+ */
+struct ast_json *stasis_json_event_application_replaced_create(
+	struct ast_json *blob
+	);
+
+/*!
+ * \brief Channel variable changed.
+ *
+ * \param channel The channel on which the variable was set.
+ * \param blob JSON blob containing the following parameters:
+ * - variable: string - The variable that changed. (required)
+ * - value: string - The new value of the variable. (required)
+ *
+ * \retval NULL on error
+ * \retval JSON (ast_json) describing the event
+ */
+struct ast_json *stasis_json_event_channel_varset_create(
+	struct ast_channel_snapshot *channel_snapshot,
+	struct ast_json *blob
+	);
+
+/*!
+ * \brief User-generated event with additional user-defined fields in the object.
+ *
+ * \param channel The channel that signaled the user event.
+ * \param blob JSON blob containing the following parameters:
+ * - eventname: string - The name of the user event. (required)
+ *
+ * \retval NULL on error
+ * \retval JSON (ast_json) describing the event
+ */
+struct ast_json *stasis_json_event_channel_userevent_create(
+	struct ast_channel_snapshot *channel_snapshot,
+	struct ast_json *blob
+	);
+
+/*!
+ * \brief Notification that a channel has been created.
+ *
+ * \param channel The channel to be used to generate this event
+ *
+ * \retval NULL on error
+ * \retval JSON (ast_json) describing the event
+ */
+struct ast_json *stasis_json_event_channel_created_create(
+	struct ast_channel_snapshot *channel_snapshot
+	);
+
+/*!
+ * \brief Notification that a channel has entered a Stasis appliction.
+ *
+ * \param channel The channel to be used to generate this event
+ * \param blob JSON blob containing the following parameters:
+ * - args: List[string] - Arguments to the application (required)
+ *
+ * \retval NULL on error
+ * \retval JSON (ast_json) describing the event
+ */
+struct ast_json *stasis_json_event_stasis_start_create(
+	struct ast_channel_snapshot *channel_snapshot,
+	struct ast_json *blob
+	);
+
+/*!
+ * \brief Channel changed location in the dialplan.
+ *
+ * \param channel The channel that changed dialplan location.
+ * \param blob JSON blob containing the following parameters:
+ * - application: string - The application that the channel is currently in. (required)
+ * - application_data: string - The data that was passed to the application when it was invoked. (required)
+ *
+ * \retval NULL on error
+ * \retval JSON (ast_json) describing the event
+ */
+struct ast_json *stasis_json_event_channel_dialplan_create(
+	struct ast_channel_snapshot *channel_snapshot,
+	struct ast_json *blob
+	);
+
+/*!
+ * \brief Notification of a channel's state change.
+ *
+ * \param channel The channel to be used to generate this event
+ *
+ * \retval NULL on error
+ * \retval JSON (ast_json) describing the event
+ */
+struct ast_json *stasis_json_event_channel_state_change_create(
+	struct ast_channel_snapshot *channel_snapshot
+	);
+
+/*!
+ * \brief DTMF received on a channel.
+ *
+ * \param channel The channel on which DTMF was received
+ * \param blob JSON blob containing the following parameters:
+ * - digit: string - DTMF digit received (0-9, A-E, # or *) (required)
+ *
+ * \retval NULL on error
+ * \retval JSON (ast_json) describing the event
+ */
+struct ast_json *stasis_json_event_channel_dtmf_received_create(
+	struct ast_channel_snapshot *channel_snapshot,
+	struct ast_json *blob
+	);
+
+/*!
+ * \brief Notification that a channel has left a Stasis appliction.
+ *
+ * \param channel The channel to be used to generate this event
+ *
+ * \retval NULL on error
+ * \retval JSON (ast_json) describing the event
+ */
+struct ast_json *stasis_json_event_stasis_end_create(
+	struct ast_channel_snapshot *channel_snapshot
+	);
+
 /*
  * JSON models
  *
- * DtmfReceived
- * - digit: string 
- * - channel: Channel 
- * BridgeCreated
- * - bridge: Bridge 
- * BridgeDestroyed
- * - bridge: Bridge 
+ * ChannelSnapshot
+ * ChannelDestroyed
+ * - cause: integer (required)
+ * - cause_txt: string (required)
+ * ChannelCallerId
+ * - caller_presentation_txt: string (required)
+ * - caller_presentation: integer (required)
+ * ChannelHangupRequest
+ * - soft: boolean
+ * - cause: integer
  * ApplicationReplaced
- * - application: string 
- * ChannelLeftBridge
- * - bridge: Bridge 
- * - channel: Channel 
+ * - application: string (required)
+ * ChannelVarset
+ * - variable: string (required)
+ * - value: string (required)
+ * ChannelUserevent
+ * - eventname: string (required)
+ * ChannelCreated
  * StasisStart
- * - args: List[string] 
- * - channel_info: Channel 
- * StasisEnd
- * - channel_info: Channel 
+ * - args: List[string] (required)
+ * ChannelDialplan
+ * - application: string (required)
+ * - application_data: string (required)
  * ChannelStateChange
- * - channel_info: Channel 
- * ChannelEnteredBridge
- * - bridge: Bridge 
- * - channel: Channel 
+ * ChannelDtmfReceived
+ * - digit: string (required)
  * Event
- * - stasis_start: StasisStart 
- * - channel_entered_bridge: ChannelEnteredBridge 
- * - channel_left_bridge: ChannelLeftBridge 
- * - application_replaced: ApplicationReplaced 
- * - channel_state_change: ChannelStateChange 
- * - bridge_created: BridgeCreated 
+ * - channel_created: ChannelCreated
+ * - channel_destroyed: ChannelDestroyed
+ * - channel_dialplan: ChannelDialplan
+ * - channel_varset: ChannelVarset
+ * - application_replaced: ApplicationReplaced
+ * - channel_state_change: ChannelStateChange
+ * - stasis_start: StasisStart
  * - application: string (required)
- * - stasis_end: StasisEnd 
- * - dtmf_received: DtmfReceived 
- * - bridge_destroyed: BridgeDestroyed 
+ * - channel_hangup_request: ChannelHangupRequest
+ * - channel_userevent: ChannelUserevent
+ * - channel_snapshot: ChannelSnapshot
+ * - channel_dtmf_received: ChannelDtmfReceived
+ * - channel_caller_id: ChannelCallerId
+ * - stasis_end: StasisEnd
+ * StasisEnd
  */
 
 #endif /* _ASTERISK_RESOURCE_EVENTS_H */
diff --git a/res/stasis_http/resource_recordings.h b/res/stasis_http/resource_recordings.h
index 549a36106..d062da996 100644
--- a/res/stasis_http/resource_recordings.h
+++ b/res/stasis_http/resource_recordings.h
@@ -196,8 +196,8 @@ void stasis_http_unmute_recording(struct ast_variable *headers, struct ast_unmut
  * Recording
  * - id: string (required)
  * StoredRecording
- * - durationSeconds: int 
- * - time: Date 
+ * - durationSeconds: int
+ * - time: Date
  * - id: string (required)
  * - formats: List[string] (required)
  * LiveRecording
diff --git a/res/stasis_http/resource_sounds.h b/res/stasis_http/resource_sounds.h
index 4af8b9dfd..9d724b359 100644
--- a/res/stasis_http/resource_sounds.h
+++ b/res/stasis_http/resource_sounds.h
@@ -71,7 +71,7 @@ void stasis_http_get_stored_sound(struct ast_variable *headers, struct ast_get_s
  *
  * Sound
  * - lang: string (required)
- * - text: string 
+ * - text: string
  * - id: string (required)
  * - formats: List[string] (required)
  */