res/ari/resource_bridges: Add the ability to manipulate the video source

In multi-party bridges, Asterisk currently supports two video modes:
 * Follow the talker, in which the speaker with the most energy is shown
   to all participants but the speaker, and the speaker sees the
   previous video source
 * Explicitly set video sources, in which all participants see a locked
   video source

Prior to this patch, ARI had no ability to manipulate the video source.
This isn't important for two-party bridges, in which Asterisk merely
relays the video between the participants. However, in a multi-party
bridge, it can be advantageous to allow an external application to
manipulate the video source.

This patch provides two new routes to accomplish this:
(1) setVideoSource: POST /bridges/{bridgeId}/videoSource/{channelId}
    Sets a video source to an explicit channel
(2) clearVideoSource: DELETE /bridges/{bridgeId}/videoSource
    Removes any explicit video source, and sets the video mode to talk
    detection

ASTERISK-26595 #close

Change-Id: I98e455d5bffc08ea5e8d6b84ccaf063c714e6621

6 files changed, 393 insertions, 2 deletions

diff --git a/res/ari/ari_model_validators.c b/res/ari/ari_model_validators.c
index 8874b2451..171cb2907 100644
--- a/res/ari/ari_model_validators.c
+++ b/res/ari/ari_model_validators.c
@@ -1360,6 +1360,24 @@ int ast_ari_validate_bridge(struct ast_json *json)
 				res = 0;
 			}
 		} else
+		if (strcmp("video_mode", ast_json_object_iter_key(iter)) == 0) {
+			int prop_is_valid;
+			prop_is_valid = ast_ari_validate_string(
+				ast_json_object_iter_value(iter));
+			if (!prop_is_valid) {
+				ast_log(LOG_ERROR, "ARI Bridge field video_mode failed validation\n");
+				res = 0;
+			}
+		} else
+		if (strcmp("video_source_id", ast_json_object_iter_key(iter)) == 0) {
+			int prop_is_valid;
+			prop_is_valid = ast_ari_validate_string(
+				ast_json_object_iter_value(iter));
+			if (!prop_is_valid) {
+				ast_log(LOG_ERROR, "ARI Bridge field video_source_id failed validation\n");
+				res = 0;
+			}
+		} else
 		{
 			ast_log(LOG_ERROR,
 				"ARI Bridge has undocumented field %s\n",
@@ -2706,6 +2724,103 @@ ari_validator ast_ari_validate_bridge_merged_fn(void)
 	return ast_ari_validate_bridge_merged;
 }
 
+int ast_ari_validate_bridge_video_source_changed(struct ast_json *json)
+{
+	int res = 1;
+	struct ast_json_iter *iter;
+	int has_type = 0;
+	int has_application = 0;
+	int has_bridge = 0;
+
+	for (iter = ast_json_object_iter(json); iter; iter = ast_json_object_iter_next(json, iter)) {
+		if (strcmp("asterisk_id", ast_json_object_iter_key(iter)) == 0) {
+			int prop_is_valid;
+			prop_is_valid = ast_ari_validate_string(
+				ast_json_object_iter_value(iter));
+			if (!prop_is_valid) {
+				ast_log(LOG_ERROR, "ARI BridgeVideoSourceChanged field asterisk_id failed validation\n");
+				res = 0;
+			}
+		} else
+		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 BridgeVideoSourceChanged 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 BridgeVideoSourceChanged 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 BridgeVideoSourceChanged field timestamp failed validation\n");
+				res = 0;
+			}
+		} else
+		if (strcmp("bridge", ast_json_object_iter_key(iter)) == 0) {
+			int prop_is_valid;
+			has_bridge = 1;
+			prop_is_valid = ast_ari_validate_bridge(
+				ast_json_object_iter_value(iter));
+			if (!prop_is_valid) {
+				ast_log(LOG_ERROR, "ARI BridgeVideoSourceChanged field bridge failed validation\n");
+				res = 0;
+			}
+		} else
+		if (strcmp("old_video_source_id", ast_json_object_iter_key(iter)) == 0) {
+			int prop_is_valid;
+			prop_is_valid = ast_ari_validate_string(
+				ast_json_object_iter_value(iter));
+			if (!prop_is_valid) {
+				ast_log(LOG_ERROR, "ARI BridgeVideoSourceChanged field old_video_source_id failed validation\n");
+				res = 0;
+			}
+		} else
+		{
+			ast_log(LOG_ERROR,
+				"ARI BridgeVideoSourceChanged has undocumented field %s\n",
+				ast_json_object_iter_key(iter));
+			res = 0;
+		}
+	}
+
+	if (!has_type) {
+		ast_log(LOG_ERROR, "ARI BridgeVideoSourceChanged missing required field type\n");
+		res = 0;
+	}
+
+	if (!has_application) {
+		ast_log(LOG_ERROR, "ARI BridgeVideoSourceChanged missing required field application\n");
+		res = 0;
+	}
+
+	if (!has_bridge) {
+		ast_log(LOG_ERROR, "ARI BridgeVideoSourceChanged missing required field bridge\n");
+		res = 0;
+	}
+
+	return res;
+}
+
+ari_validator ast_ari_validate_bridge_video_source_changed_fn(void)
+{
+	return ast_ari_validate_bridge_video_source_changed;
+}
+
 int ast_ari_validate_channel_caller_id(struct ast_json *json)
 {
 	int res = 1;
@@ -4912,6 +5027,9 @@ int ast_ari_validate_event(struct ast_json *json)
 	if (strcmp("BridgeMerged", discriminator) == 0) {
 		return ast_ari_validate_bridge_merged(json);
 	} else
+	if (strcmp("BridgeVideoSourceChanged", discriminator) == 0) {
+		return ast_ari_validate_bridge_video_source_changed(json);
+	} else
 	if (strcmp("ChannelCallerId", discriminator) == 0) {
 		return ast_ari_validate_channel_caller_id(json);
 	} else
@@ -5104,6 +5222,9 @@ int ast_ari_validate_message(struct ast_json *json)
 	if (strcmp("BridgeMerged", discriminator) == 0) {
 		return ast_ari_validate_bridge_merged(json);
 	} else
+	if (strcmp("BridgeVideoSourceChanged", discriminator) == 0) {
+		return ast_ari_validate_bridge_video_source_changed(json);
+	} else
 	if (strcmp("ChannelCallerId", discriminator) == 0) {
 		return ast_ari_validate_channel_caller_id(json);
 	} else
diff --git a/res/ari/ari_model_validators.h b/res/ari/ari_model_validators.h
index 750518383..403a5fb17 100644
--- a/res/ari/ari_model_validators.h
+++ b/res/ari/ari_model_validators.h
@@ -717,6 +717,24 @@ int ast_ari_validate_bridge_merged(struct ast_json *json);
 ari_validator ast_ari_validate_bridge_merged_fn(void);
 
 /*!
+ * \brief Validator for BridgeVideoSourceChanged.
+ *
+ * Notification that the source of video in a bridge has changed.
+ *
+ * \param json JSON object to validate.
+ * \returns True (non-zero) if valid.
+ * \returns False (zero) if invalid.
+ */
+int ast_ari_validate_bridge_video_source_changed(struct ast_json *json);
+
+/*!
+ * \brief Function pointer to ast_ari_validate_bridge_video_source_changed().
+ *
+ * See \ref ast_ari_model_validators.h for more details.
+ */
+ari_validator ast_ari_validate_bridge_video_source_changed_fn(void);
+
+/*!
  * \brief Validator for ChannelCallerId.
  *
  * Channel changed Caller ID.
@@ -1434,6 +1452,8 @@ ari_validator ast_ari_validate_application_fn(void);
  * - id: string (required)
  * - name: string (required)
  * - technology: string (required)
+ * - video_mode: string
+ * - video_source_id: string
  * LiveRecording
  * - cause: string
  * - duration: int
@@ -1524,6 +1544,13 @@ ari_validator ast_ari_validate_application_fn(void);
  * - timestamp: Date
  * - bridge: Bridge (required)
  * - bridge_from: Bridge (required)
+ * BridgeVideoSourceChanged
+ * - asterisk_id: string
+ * - type: string (required)
+ * - application: string (required)
+ * - timestamp: Date
+ * - bridge: Bridge (required)
+ * - old_video_source_id: string
  * ChannelCallerId
  * - asterisk_id: string
  * - type: string (required)
diff --git a/res/ari/resource_bridges.c b/res/ari/resource_bridges.c
index 39709d022..8c058c4a7 100644
--- a/res/ari/resource_bridges.c
+++ b/res/ari/resource_bridges.c
@@ -37,6 +37,7 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 #include "asterisk/stasis.h"
 #include "asterisk/stasis_bridges.h"
 #include "asterisk/stasis_app.h"
+#include "asterisk/stasis_app_impl.h"
 #include "asterisk/stasis_app_playback.h"
 #include "asterisk/stasis_app_recording.h"
 #include "asterisk/stasis_channels.h"
@@ -998,3 +999,68 @@ void ast_ari_bridges_create_with_id(struct ast_variable *headers,
 	ast_ari_response_ok(response,
 		ast_bridge_snapshot_to_json(snapshot, stasis_app_get_sanitizer()));
 }
+
+static int bridge_set_video_source_cb(struct stasis_app_control *control,
+	struct ast_channel *chan, void *data)
+{
+	struct ast_bridge *bridge = data;
+
+	ast_bridge_lock(bridge);
+	ast_bridge_set_single_src_video_mode(bridge, chan);
+	ast_bridge_unlock(bridge);
+
+	return 0;
+}
+
+void ast_ari_bridges_set_video_source(struct ast_variable *headers,
+	struct ast_ari_bridges_set_video_source_args *args, struct ast_ari_response *response)
+{
+	struct ast_bridge *bridge;
+	struct stasis_app_control *control;
+
+	bridge = find_bridge(response, args->bridge_id);
+	if (!bridge) {
+		return;
+	}
+
+	control = find_channel_control(response, args->channel_id);
+	if (!control) {
+		ao2_ref(bridge, -1);
+		return;
+	}
+
+	if (stasis_app_get_bridge(control) != bridge) {
+		ast_ari_response_error(response, 422,
+			"Unprocessable Entity",
+			"Channel not in this bridge");
+		ao2_ref(bridge, -1);
+		ao2_ref(control, -1);
+		return;
+	}
+
+	stasis_app_send_command(control, bridge_set_video_source_cb,
+		ao2_bump(bridge), __ao2_cleanup);
+
+	ao2_ref(bridge, -1);
+	ao2_ref(control, -1);
+
+	ast_ari_response_no_content(response);
+}
+
+void ast_ari_bridges_clear_video_source(struct ast_variable *headers,
+	struct ast_ari_bridges_clear_video_source_args *args, struct ast_ari_response *response)
+{
+	struct ast_bridge *bridge;
+
+	bridge = find_bridge(response, args->bridge_id);
+	if (!bridge) {
+		return;
+	}
+
+	ast_bridge_lock(bridge);
+	ast_bridge_set_talker_src_video_mode(bridge);
+	ast_bridge_unlock(bridge);
+
+	ao2_ref(bridge, -1);
+	ast_ari_response_no_content(response);
+}
diff --git a/res/ari/resource_bridges.h b/res/ari/resource_bridges.h
index 36ff6a017..61fc6bb78 100644
--- a/res/ari/resource_bridges.h
+++ b/res/ari/resource_bridges.h
@@ -200,6 +200,34 @@ int ast_ari_bridges_remove_channel_parse_body(
  * \param[out] response HTTP response
  */
 void ast_ari_bridges_remove_channel(struct ast_variable *headers, struct ast_ari_bridges_remove_channel_args *args, struct ast_ari_response *response);
+/*! Argument struct for ast_ari_bridges_set_video_source() */
+struct ast_ari_bridges_set_video_source_args {
+	/*! Bridge's id */
+	const char *bridge_id;
+	/*! Channel's id */
+	const char *channel_id;
+};
+/*!
+ * \brief Set a channel as the video source in a multi-party mixing bridge. This operation has no effect on bridges with two or fewer participants.
+ *
+ * \param headers HTTP headers
+ * \param args Swagger parameters
+ * \param[out] response HTTP response
+ */
+void ast_ari_bridges_set_video_source(struct ast_variable *headers, struct ast_ari_bridges_set_video_source_args *args, struct ast_ari_response *response);
+/*! Argument struct for ast_ari_bridges_clear_video_source() */
+struct ast_ari_bridges_clear_video_source_args {
+	/*! Bridge's id */
+	const char *bridge_id;
+};
+/*!
+ * \brief Removes any explicit video source in a multi-party mixing bridge. This operation has no effect on bridges with two or fewer participants. When no explicit video source is set, talk detection will be used to determine the active video stream.
+ *
+ * \param headers HTTP headers
+ * \param args Swagger parameters
+ * \param[out] response HTTP response
+ */
+void ast_ari_bridges_clear_video_source(struct ast_variable *headers, struct ast_ari_bridges_clear_video_source_args *args, struct ast_ari_response *response);
 /*! Argument struct for ast_ari_bridges_start_moh() */
 struct ast_ari_bridges_start_moh_args {
 	/*! Bridge's id */
diff --git a/res/res_ari_bridges.c b/res/res_ari_bridges.c
index 889d42213..458192d88 100644
--- a/res/res_ari_bridges.c
+++ b/res/res_ari_bridges.c
@@ -769,6 +769,129 @@ fin: __attribute__((unused))
 	ast_free(args.channel);
 	return;
 }
+/*!
+ * \brief Parameter parsing callback for /bridges/{bridgeId}/videoSource/{channelId}.
+ * \param get_params GET parameters in the HTTP request.
+ * \param path_vars Path variables extracted from the request.
+ * \param headers HTTP headers.
+ * \param[out] response Response to the HTTP request.
+ */
+static void ast_ari_bridges_set_video_source_cb(
+	struct ast_tcptls_session_instance *ser,
+	struct ast_variable *get_params, struct ast_variable *path_vars,
+	struct ast_variable *headers, struct ast_ari_response *response)
+{
+	struct ast_ari_bridges_set_video_source_args args = {};
+	struct ast_variable *i;
+	RAII_VAR(struct ast_json *, body, NULL, ast_json_unref);
+#if defined(AST_DEVMODE)
+	int is_valid;
+	int code;
+#endif /* AST_DEVMODE */
+
+	for (i = path_vars; i; i = i->next) {
+		if (strcmp(i->name, "bridgeId") == 0) {
+			args.bridge_id = (i->value);
+		} else
+		if (strcmp(i->name, "channelId") == 0) {
+			args.channel_id = (i->value);
+		} else
+		{}
+	}
+	ast_ari_bridges_set_video_source(headers, &args, response);
+#if defined(AST_DEVMODE)
+	code = response->response_code;
+
+	switch (code) {
+	case 0: /* Implementation is still a stub, or the code wasn't set */
+		is_valid = response->message == NULL;
+		break;
+	case 500: /* Internal Server Error */
+	case 501: /* Not Implemented */
+	case 404: /* Bridge or Channel not found */
+	case 409: /* Channel not in Stasis application */
+	case 422: /* Channel not in this Bridge */
+		is_valid = 1;
+		break;
+	default:
+		if (200 <= code && code <= 299) {
+			is_valid = ast_ari_validate_void(
+				response->message);
+		} else {
+			ast_log(LOG_ERROR, "Invalid error response %d for /bridges/{bridgeId}/videoSource/{channelId}\n", code);
+			is_valid = 0;
+		}
+	}
+
+	if (!is_valid) {
+		ast_log(LOG_ERROR, "Response validation failed for /bridges/{bridgeId}/videoSource/{channelId}\n");
+		ast_ari_response_error(response, 500,
+			"Internal Server Error", "Response validation failed");
+	}
+#endif /* AST_DEVMODE */
+
+fin: __attribute__((unused))
+	return;
+}
+/*!
+ * \brief Parameter parsing callback for /bridges/{bridgeId}/videoSource.
+ * \param get_params GET parameters in the HTTP request.
+ * \param path_vars Path variables extracted from the request.
+ * \param headers HTTP headers.
+ * \param[out] response Response to the HTTP request.
+ */
+static void ast_ari_bridges_clear_video_source_cb(
+	struct ast_tcptls_session_instance *ser,
+	struct ast_variable *get_params, struct ast_variable *path_vars,
+	struct ast_variable *headers, struct ast_ari_response *response)
+{
+	struct ast_ari_bridges_clear_video_source_args args = {};
+	struct ast_variable *i;
+	RAII_VAR(struct ast_json *, body, NULL, ast_json_unref);
+#if defined(AST_DEVMODE)
+	int is_valid;
+	int code;
+#endif /* AST_DEVMODE */
+
+	for (i = path_vars; i; i = i->next) {
+		if (strcmp(i->name, "bridgeId") == 0) {
+			args.bridge_id = (i->value);
+		} else
+		{}
+	}
+	ast_ari_bridges_clear_video_source(headers, &args, response);
+#if defined(AST_DEVMODE)
+	code = response->response_code;
+
+	switch (code) {
+	case 0: /* Implementation is still a stub, or the code wasn't set */
+		is_valid = response->message == NULL;
+		break;
+	case 500: /* Internal Server Error */
+	case 501: /* Not Implemented */
+	case 404: /* Bridge not found */
+		is_valid = 1;
+		break;
+	default:
+		if (200 <= code && code <= 299) {
+			is_valid = ast_ari_validate_void(
+				response->message);
+		} else {
+			ast_log(LOG_ERROR, "Invalid error response %d for /bridges/{bridgeId}/videoSource\n", code);
+			is_valid = 0;
+		}
+	}
+
+	if (!is_valid) {
+		ast_log(LOG_ERROR, "Response validation failed for /bridges/{bridgeId}/videoSource\n");
+		ast_ari_response_error(response, 500,
+			"Internal Server Error", "Response validation failed");
+	}
+#endif /* AST_DEVMODE */
+
+fin: __attribute__((unused))
+	return;
+}
 int ast_ari_bridges_start_moh_parse_body(
 	struct ast_json *body,
 	struct ast_ari_bridges_start_moh_args *args)
@@ -1337,6 +1460,25 @@ static struct stasis_rest_handlers bridges_bridgeId_removeChannel = {
 	.children = {  }
 };
 /*! \brief REST handler for /api-docs/bridges.json */
+static struct stasis_rest_handlers bridges_bridgeId_videoSource_channelId = {
+	.path_segment = "channelId",
+	.is_wildcard = 1,
+	.callbacks = {
+		[AST_HTTP_POST] = ast_ari_bridges_set_video_source_cb,
+	},
+	.num_children = 0,
+	.children = {  }
+};
+/*! \brief REST handler for /api-docs/bridges.json */
+static struct stasis_rest_handlers bridges_bridgeId_videoSource = {
+	.path_segment = "videoSource",
+	.callbacks = {
+		[AST_HTTP_DELETE] = ast_ari_bridges_clear_video_source_cb,
+	},
+	.num_children = 1,
+	.children = { &bridges_bridgeId_videoSource_channelId, }
+};
+/*! \brief REST handler for /api-docs/bridges.json */
 static struct stasis_rest_handlers bridges_bridgeId_moh = {
 	.path_segment = "moh",
 	.callbacks = {
@@ -1383,8 +1525,8 @@ static struct stasis_rest_handlers bridges_bridgeId = {
 		[AST_HTTP_GET] = ast_ari_bridges_get_cb,
 		[AST_HTTP_DELETE] = ast_ari_bridges_destroy_cb,
 	},
-	.num_children = 5,
-	.children = { &bridges_bridgeId_addChannel,&bridges_bridgeId_removeChannel,&bridges_bridgeId_moh,&bridges_bridgeId_play,&bridges_bridgeId_record, }
+	.num_children = 6,
+	.children = { &bridges_bridgeId_addChannel,&bridges_bridgeId_removeChannel,&bridges_bridgeId_videoSource,&bridges_bridgeId_moh,&bridges_bridgeId_play,&bridges_bridgeId_record, }
 };
 /*! \brief REST handler for /api-docs/bridges.json */
 static struct stasis_rest_handlers bridges = {
diff --git a/res/stasis/app.c b/res/stasis/app.c
index b2d9529bf..0bef0ee57 100644
--- a/res/stasis/app.c
+++ b/res/stasis/app.c
@@ -701,6 +701,13 @@ static void sub_bridge_update_handler(void *data,
 		json = simple_bridge_event("BridgeDestroyed", old_snapshot, tv);
 	} else if (!old_snapshot) {
 		json = simple_bridge_event("BridgeCreated", new_snapshot, tv);
+	} else if (new_snapshot && old_snapshot
+		&& strcmp(new_snapshot->video_source_id, old_snapshot->video_source_id)) {
+		json = simple_bridge_event("BridgeVideoSourceChanged", new_snapshot, tv);
+		if (json && !ast_strlen_zero(old_snapshot->video_source_id)) {
+			ast_json_object_set(json, "old_video_source_id",
+				ast_json_string_create(old_snapshot->video_source_id));
+		}
 	}
 
 	if (json) {