ARI: Implement device state API

Created a data model and implemented functionality for an ARI device state
resource.  The following operations have been added that allow a user to
manipulate an ARI controlled device:

Create/Change the state of an ARI controlled device
PUT    /deviceStates/{deviceName}&{deviceState}

Retrieve all ARI controlled devices
GET    /deviceStates

Retrieve the current state of a device
GET    /deviceStates/{deviceName}

Destroy a device-state controlled by ARI
DELETE /deviceStates/{deviceName}

The ARI controlled device must begin with 'Stasis:'.  An example controlled
device name would be Stasis:Example.  A 'DeviceStateChanged' event has also
been added so that an application can subscribe and receive device change
events.  Any device state, ARI controlled or not, can be subscribed to.

While adding the event, the underlying subscription control mechanism was
refactored so that all current and future resource subscriptions would be
the same.  Each event resource must now register itself in order to be able
to properly handle [un]subscribes.

(issue ASTERISK-22838)
Reported by: Matt Jordan
Review: https://reviewboard.asterisk.org/r/3025/
........

Merged revisions 403134 from http://svn.asterisk.org/svn/asterisk/branches/12


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

5 files changed, 409 insertions, 2 deletions

diff --git a/res/ari/ari_model_validators.c b/res/ari/ari_model_validators.c
index 9ea2f94cd..f84a92ed7 100644
--- a/res/ari/ari_model_validators.c
+++ b/res/ari/ari_model_validators.c
@@ -1333,6 +1333,60 @@ ari_validator ast_ari_validate_playback_fn(void)
 	return ast_ari_validate_playback;
 }
 
+int ast_ari_validate_device_state(struct ast_json *json)
+{
+	int res = 1;
+	struct ast_json_iter *iter;
+	int has_name = 0;
+	int has_state = 0;
+
+	for (iter = ast_json_object_iter(json); iter; iter = ast_json_object_iter_next(json, iter)) {
+		if (strcmp("name", ast_json_object_iter_key(iter)) == 0) {
+			int prop_is_valid;
+			has_name = 1;
+			prop_is_valid = ast_ari_validate_string(
+				ast_json_object_iter_value(iter));
+			if (!prop_is_valid) {
+				ast_log(LOG_ERROR, "ARI DeviceState field name failed validation\n");
+				res = 0;
+			}
+		} else
+		if (strcmp("state", ast_json_object_iter_key(iter)) == 0) {
+			int prop_is_valid;
+			has_state = 1;
+			prop_is_valid = ast_ari_validate_string(
+				ast_json_object_iter_value(iter));
+			if (!prop_is_valid) {
+				ast_log(LOG_ERROR, "ARI DeviceState field state failed validation\n");
+				res = 0;
+			}
+		} else
+		{
+			ast_log(LOG_ERROR,
+				"ARI DeviceState has undocumented field %s\n",
+				ast_json_object_iter_key(iter));
+			res = 0;
+		}
+	}
+
+	if (!has_name) {
+		ast_log(LOG_ERROR, "ARI DeviceState missing required field name\n");
+		res = 0;
+	}
+
+	if (!has_state) {
+		ast_log(LOG_ERROR, "ARI DeviceState missing required field state\n");
+		res = 0;
+	}
+
+	return res;
+}
+
+ari_validator ast_ari_validate_device_state_fn(void)
+{
+	return ast_ari_validate_device_state;
+}
+
 int ast_ari_validate_application_replaced(struct ast_json *json)
 {
 	int res = 1;
@@ -2746,6 +2800,85 @@ ari_validator ast_ari_validate_channel_varset_fn(void)
 	return ast_ari_validate_channel_varset;
 }
 
+int ast_ari_validate_device_state_changed(struct ast_json *json)
+{
+	int res = 1;
+	struct ast_json_iter *iter;
+	int has_type = 0;
+	int has_application = 0;
+	int has_device_state = 0;
+
+	for (iter = ast_json_object_iter(json); iter; iter = ast_json_object_iter_next(json, iter)) {
+		if (strcmp("type", ast_json_object_iter_key(iter)) == 0) {
+			int prop_is_valid;
+			has_type = 1;
+			prop_is_valid = ast_ari_validate_string(
+				ast_json_object_iter_value(iter));
+			if (!prop_is_valid) {
+				ast_log(LOG_ERROR, "ARI DeviceStateChanged field type failed validation\n");
+				res = 0;
+			}
+		} else
+		if (strcmp("application", ast_json_object_iter_key(iter)) == 0) {
+			int prop_is_valid;
+			has_application = 1;
+			prop_is_valid = ast_ari_validate_string(
+				ast_json_object_iter_value(iter));
+			if (!prop_is_valid) {
+				ast_log(LOG_ERROR, "ARI DeviceStateChanged field application failed validation\n");
+				res = 0;
+			}
+		} else
+		if (strcmp("timestamp", ast_json_object_iter_key(iter)) == 0) {
+			int prop_is_valid;
+			prop_is_valid = ast_ari_validate_date(
+				ast_json_object_iter_value(iter));
+			if (!prop_is_valid) {
+				ast_log(LOG_ERROR, "ARI DeviceStateChanged field timestamp failed validation\n");
+				res = 0;
+			}
+		} else
+		if (strcmp("device_state", ast_json_object_iter_key(iter)) == 0) {
+			int prop_is_valid;
+			has_device_state = 1;
+			prop_is_valid = ast_ari_validate_device_state(
+				ast_json_object_iter_value(iter));
+			if (!prop_is_valid) {
+				ast_log(LOG_ERROR, "ARI DeviceStateChanged field device_state failed validation\n");
+				res = 0;
+			}
+		} else
+		{
+			ast_log(LOG_ERROR,
+				"ARI DeviceStateChanged has undocumented field %s\n",
+				ast_json_object_iter_key(iter));
+			res = 0;
+		}
+	}
+
+	if (!has_type) {
+		ast_log(LOG_ERROR, "ARI DeviceStateChanged missing required field type\n");
+		res = 0;
+	}
+
+	if (!has_application) {
+		ast_log(LOG_ERROR, "ARI DeviceStateChanged missing required field application\n");
+		res = 0;
+	}
+
+	if (!has_device_state) {
+		ast_log(LOG_ERROR, "ARI DeviceStateChanged missing required field device_state\n");
+		res = 0;
+	}
+
+	return res;
+}
+
+ari_validator ast_ari_validate_device_state_changed_fn(void)
+{
+	return ast_ari_validate_device_state_changed;
+}
+
 int ast_ari_validate_endpoint_state_change(struct ast_json *json)
 {
 	int res = 1;
@@ -2887,6 +3020,9 @@ int ast_ari_validate_event(struct ast_json *json)
 	if (strcmp("ChannelVarset", discriminator) == 0) {
 		return ast_ari_validate_channel_varset(json);
 	} else
+	if (strcmp("DeviceStateChanged", discriminator) == 0) {
+		return ast_ari_validate_device_state_changed(json);
+	} else
 	if (strcmp("EndpointStateChange", discriminator) == 0) {
 		return ast_ari_validate_endpoint_state_change(json);
 	} else
@@ -3025,6 +3161,9 @@ int ast_ari_validate_message(struct ast_json *json)
 	if (strcmp("ChannelVarset", discriminator) == 0) {
 		return ast_ari_validate_channel_varset(json);
 	} else
+	if (strcmp("DeviceStateChanged", discriminator) == 0) {
+		return ast_ari_validate_device_state_changed(json);
+	} else
 	if (strcmp("EndpointStateChange", discriminator) == 0) {
 		return ast_ari_validate_endpoint_state_change(json);
 	} else
@@ -3592,6 +3731,7 @@ int ast_ari_validate_application(struct ast_json *json)
 	struct ast_json_iter *iter;
 	int has_bridge_ids = 0;
 	int has_channel_ids = 0;
+	int has_device_names = 0;
 	int has_endpoint_ids = 0;
 	int has_name = 0;
 
@@ -3618,6 +3758,17 @@ int ast_ari_validate_application(struct ast_json *json)
 				res = 0;
 			}
 		} else
+		if (strcmp("device_names", ast_json_object_iter_key(iter)) == 0) {
+			int prop_is_valid;
+			has_device_names = 1;
+			prop_is_valid = ast_ari_validate_list(
+				ast_json_object_iter_value(iter),
+				ast_ari_validate_string);
+			if (!prop_is_valid) {
+				ast_log(LOG_ERROR, "ARI Application field device_names failed validation\n");
+				res = 0;
+			}
+		} else
 		if (strcmp("endpoint_ids", ast_json_object_iter_key(iter)) == 0) {
 			int prop_is_valid;
 			has_endpoint_ids = 1;
@@ -3657,6 +3808,11 @@ int ast_ari_validate_application(struct ast_json *json)
 		res = 0;
 	}
 
+	if (!has_device_names) {
+		ast_log(LOG_ERROR, "ARI Application missing required field device_names\n");
+		res = 0;
+	}
+
 	if (!has_endpoint_ids) {
 		ast_log(LOG_ERROR, "ARI Application missing required field endpoint_ids\n");
 		res = 0;
diff --git a/res/ari/ari_model_validators.h b/res/ari/ari_model_validators.h
index a1e5b099e..979fa4a47 100644
--- a/res/ari/ari_model_validators.h
+++ b/res/ari/ari_model_validators.h
@@ -481,6 +481,24 @@ int ast_ari_validate_playback(struct ast_json *json);
 ari_validator ast_ari_validate_playback_fn(void);
 
 /*!
+ * \brief Validator for DeviceState.
+ *
+ * Represents the state of a device.
+ *
+ * \param json JSON object to validate.
+ * \returns True (non-zero) if valid.
+ * \returns False (zero) if invalid.
+ */
+int ast_ari_validate_device_state(struct ast_json *json);
+
+/*!
+ * \brief Function pointer to ast_ari_validate_device_state().
+ *
+ * See \ref ast_ari_model_validators.h for more details.
+ */
+ari_validator ast_ari_validate_device_state_fn(void);
+
+/*!
  * \brief Validator for ApplicationReplaced.
  *
  * Notification that another WebSocket has taken over for an application.
@@ -755,6 +773,24 @@ int ast_ari_validate_channel_varset(struct ast_json *json);
 ari_validator ast_ari_validate_channel_varset_fn(void);
 
 /*!
+ * \brief Validator for DeviceStateChanged.
+ *
+ * Notification that a device state has changed.
+ *
+ * \param json JSON object to validate.
+ * \returns True (non-zero) if valid.
+ * \returns False (zero) if invalid.
+ */
+int ast_ari_validate_device_state_changed(struct ast_json *json);
+
+/*!
+ * \brief Function pointer to ast_ari_validate_device_state_changed().
+ *
+ * See \ref ast_ari_model_validators.h for more details.
+ */
+ari_validator ast_ari_validate_device_state_changed_fn(void);
+
+/*!
  * \brief Validator for EndpointStateChange.
  *
  * Endpoint state changed.
@@ -1052,6 +1088,9 @@ ari_validator ast_ari_validate_application_fn(void);
  * - media_uri: string (required)
  * - state: string (required)
  * - target_uri: string (required)
+ * DeviceState
+ * - name: string (required)
+ * - state: string (required)
  * ApplicationReplaced
  * - type: string (required)
  * - application: string (required)
@@ -1143,6 +1182,11 @@ ari_validator ast_ari_validate_application_fn(void);
  * - channel: Channel
  * - value: string (required)
  * - variable: string (required)
+ * DeviceStateChanged
+ * - type: string (required)
+ * - application: string (required)
+ * - timestamp: Date
+ * - device_state: DeviceState (required)
  * EndpointStateChange
  * - type: string (required)
  * - application: string (required)
@@ -1187,6 +1231,7 @@ ari_validator ast_ari_validate_application_fn(void);
  * Application
  * - bridge_ids: List[string] (required)
  * - channel_ids: List[string] (required)
+ * - device_names: List[string] (required)
  * - endpoint_ids: List[string] (required)
  * - name: string (required)
  */
diff --git a/res/ari/resource_applications.h b/res/ari/resource_applications.h
index 12aacb330..6aebd07fd 100644
--- a/res/ari/resource_applications.h
+++ b/res/ari/resource_applications.h
@@ -67,7 +67,7 @@ void ast_ari_applications_get(struct ast_variable *headers, struct ast_ari_appli
 struct ast_ari_applications_subscribe_args {
 	/*! \brief Application's name */
 	const char *application_name;
-	/*! \brief Array of URI for event source (channel:{channelId}, bridge:{bridgeId}, endpoint:{tech}/{resource} */
+	/*! \brief Array of URI for event source (channel:{channelId}, bridge:{bridgeId}, endpoint:{tech}/{resource}, deviceState:{deviceName} */
 	const char **event_source;
 	/*! \brief Length of event_source array. */
 	size_t event_source_count;
@@ -88,7 +88,7 @@ void ast_ari_applications_subscribe(struct ast_variable *headers, struct ast_ari
 struct ast_ari_applications_unsubscribe_args {
 	/*! \brief Application's name */
 	const char *application_name;
-	/*! \brief Array of URI for event source (channel:{channelId}, bridge:{bridgeId}, endpoint:{tech}/{resource} */
+	/*! \brief Array of URI for event source (channel:{channelId}, bridge:{bridgeId}, endpoint:{tech}/{resource}, device_state:{deviceName} */
 	const char **event_source;
 	/*! \brief Length of event_source array. */
 	size_t event_source_count;
diff --git a/res/ari/resource_device_states.c b/res/ari/resource_device_states.c
new file mode 100644
index 000000000..50b876740
--- /dev/null
+++ b/res/ari/resource_device_states.c
@@ -0,0 +1,111 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2012 - 2013, Digium, Inc.
+ *
+ * Kevin Harwell <kharwell@digium.com>
+ *
+ * See http://www.asterisk.org for more information about
+ * the Asterisk project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
+ */
+
+/*! \file
+ *
+ * \brief /api-docs/deviceStates.{format} implementation- Device state resources
+ *
+ * \author Kevin Harwell <kharwell@digium.com>
+ */
+
+#include "asterisk.h"
+
+ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
+
+#include "resource_device_states.h"
+#include "asterisk/stasis_app_device_state.h"
+
+void ast_ari_device_states_list(
+	struct ast_variable *headers,
+	struct ast_ari_device_states_list_args *args,
+	struct ast_ari_response *response)
+{
+	RAII_VAR(struct ast_json *, json, NULL, ast_json_unref);
+
+	if (!(json = stasis_app_device_states_to_json())) {
+		ast_ari_response_error(response, 500,
+			"Internal Server Error", "Error building response");
+		return;
+	}
+
+	ast_ari_response_ok(response, json);
+}
+
+void ast_ari_device_states_get(struct ast_variable *headers,
+	struct ast_ari_device_states_get_args *args,
+	struct ast_ari_response *response)
+{
+	RAII_VAR(struct ast_json *, json, NULL, ast_json_unref);
+
+	if (!(json = stasis_app_device_state_to_json(
+		      args->device_name, ast_device_state(args->device_name)))) {
+		ast_ari_response_error(response, 500,
+			"Internal Server Error", "Error building response");
+		return;
+	}
+
+	ast_ari_response_ok(response, json);
+}
+
+void ast_ari_device_states_update(struct ast_variable *headers,
+	struct ast_ari_device_states_update_args *args,
+	struct ast_ari_response *response)
+{
+	switch (stasis_app_device_state_update(
+			args->device_name, args->device_state)) {
+	case STASIS_DEVICE_STATE_NOT_CONTROLLED:
+		ast_ari_response_error(response, 409,
+			"Conflict", "Uncontrolled device specified");
+		return;
+	case STASIS_DEVICE_STATE_MISSING:
+		ast_ari_response_error(response, 404,
+			"Not Found", "Device name is missing");
+		return;
+	case STASIS_DEVICE_STATE_UNKNOWN:
+		ast_ari_response_error(response, 500, "Internal Server Error",
+				       "Unknown device");
+		return;
+	case STASIS_DEVICE_STATE_OK:
+	case STASIS_DEVICE_STATE_SUBSCRIBERS: /* shouldn't be returned for update */
+		ast_ari_response_no_content(response);
+	}
+}
+
+void ast_ari_device_states_delete(struct ast_variable *headers,
+	struct ast_ari_device_states_delete_args *args,
+	struct ast_ari_response *response)
+{
+	switch (stasis_app_device_state_delete(args->device_name)) {
+	case STASIS_DEVICE_STATE_NOT_CONTROLLED:
+		ast_ari_response_error(response, 409,
+			"Conflict", "Uncontrolled device specified");
+		return;
+	case STASIS_DEVICE_STATE_MISSING:
+		ast_ari_response_error(response, 404,
+			"Not Found", "Device name is missing");
+		return;
+	case STASIS_DEVICE_STATE_SUBSCRIBERS:
+		ast_ari_response_error(response, 500,
+			"Internal Server Error",
+			"Cannot delete device with subscribers");
+		return;
+	case STASIS_DEVICE_STATE_OK:
+	case STASIS_DEVICE_STATE_UNKNOWN:
+		ast_ari_response_no_content(response);
+	}
+}
diff --git a/res/ari/resource_device_states.h b/res/ari/resource_device_states.h
new file mode 100644
index 000000000..a3bac999c
--- /dev/null
+++ b/res/ari/resource_device_states.h
@@ -0,0 +1,95 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2012 - 2013, Digium, Inc.
+ *
+ * Kevin Harwell <kharwell@digium.com>
+ *
+ * See http://www.asterisk.org for more information about
+ * the Asterisk project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
+ */
+
+/*! \file
+ *
+ * \brief Generated file - declares stubs to be implemented in
+ * res/ari/resource_deviceStates.c
+ *
+ * Device state resources
+ *
+ * \author Kevin Harwell <kharwell@digium.com>
+ */
+
+/*
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ * !!!!!                               DO NOT EDIT                        !!!!!
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ * This file is generated by a mustache template. Please see the original
+ * template in rest-api-templates/ari_resource.h.mustache
+ */
+
+#ifndef _ASTERISK_RESOURCE_DEVICESTATES_H
+#define _ASTERISK_RESOURCE_DEVICESTATES_H
+
+#include "asterisk/ari.h"
+
+/*! \brief Argument struct for ast_ari_device_states_list() */
+struct ast_ari_device_states_list_args {
+};
+/*!
+ * \brief List all ARI controlled device states.
+ *
+ * \param headers HTTP headers
+ * \param args Swagger parameters
+ * \param[out] response HTTP response
+ */
+void ast_ari_device_states_list(struct ast_variable *headers, struct ast_ari_device_states_list_args *args, struct ast_ari_response *response);
+/*! \brief Argument struct for ast_ari_device_states_get() */
+struct ast_ari_device_states_get_args {
+	/*! \brief Name of the device */
+	const char *device_name;
+};
+/*!
+ * \brief Retrieve the current state of a device.
+ *
+ * \param headers HTTP headers
+ * \param args Swagger parameters
+ * \param[out] response HTTP response
+ */
+void ast_ari_device_states_get(struct ast_variable *headers, struct ast_ari_device_states_get_args *args, struct ast_ari_response *response);
+/*! \brief Argument struct for ast_ari_device_states_update() */
+struct ast_ari_device_states_update_args {
+	/*! \brief Name of the device */
+	const char *device_name;
+	/*! \brief Device state value */
+	const char *device_state;
+};
+/*!
+ * \brief Change the state of a device controlled by ARI. (Note - implicitly creates the device state).
+ *
+ * \param headers HTTP headers
+ * \param args Swagger parameters
+ * \param[out] response HTTP response
+ */
+void ast_ari_device_states_update(struct ast_variable *headers, struct ast_ari_device_states_update_args *args, struct ast_ari_response *response);
+/*! \brief Argument struct for ast_ari_device_states_delete() */
+struct ast_ari_device_states_delete_args {
+	/*! \brief Name of the device */
+	const char *device_name;
+};
+/*!
+ * \brief Destroy a device-state controlled by ARI.
+ *
+ * \param headers HTTP headers
+ * \param args Swagger parameters
+ * \param[out] response HTTP response
+ */
+void ast_ari_device_states_delete(struct ast_variable *headers, struct ast_ari_device_states_delete_args *args, struct ast_ari_response *response);
+
+#endif /* _ASTERISK_RESOURCE_DEVICESTATES_H */