ARI: Add the ability to play multiple media URIs in a single operation

Many ARI applications will want to play multiple media files in a row to
a resource. The most common use case is when building long-ish IVR prompts
made up of multiple, smaller sound files. Today, that requires building a
small state machine, listening for each PlaybackFinished event, and triggering
the next sound file to play. While not especially challenging, it is tedious
work. Since requiring developers to write tedious code to do normal activities
stinks, this patch adds the ability to play back a list of media files to a
resource.

Each of the 'play' operations on supported resources (channels and bridges)
now accepts a comma delineated list of media URIs to play. A single Playback
resource is created as a handle to the entire list. The operation of playing
a list is identical to playing a single media URI, save that a new event,
PlaybackContinuing, is raised instead of a PlaybackFinished for each non-final
media URI. When the entire list is finished being played, a PlaybackFinished
event is raised.

In order to help inform applications where they are in the list playback, the
Playback resource now includes a new, optional attribute, 'next_media_uri',
that contains the next URI in the list to be played.

It's important to note the following:
 - If an offset is provided to the 'play' operations, it only applies to the
   first media URI, as it would be weird to skip n seconds forward in every
   media resource.
 - Operations that control the position of the media only affect the current
   media being played. For example, once a media resource in the list
   completes, a 'reverse' operation on a subsequent media resource will not
   start a previously completed media resource at the appropiate offset.
 - This patch does not add any new operations to control the list. Hopefully,
   user feedback and/or future patches would add that if people want it.

ASTERISK-26022 #close

Change-Id: Ie1ea5356573447b8f51f2e7964915ea01792f16f

1 files changed, 138 insertions, 4 deletions

diff --git a/res/res_ari_bridges.c b/res/res_ari_bridges.c
index 633dc94eb..119687999 100644
--- a/res/res_ari_bridges.c
+++ b/res/res_ari_bridges.c
@@ -935,7 +935,32 @@ int ast_ari_bridges_play_parse_body(
 	/* Parse query parameters out of it */
 	field = ast_json_object_get(body, "media");
 	if (field) {
-		args->media = ast_json_string_get(field);
+		/* If they were silly enough to both pass in a query param and a
+		 * JSON body, free up the query value.
+		 */
+		ast_free(args->media);
+		if (ast_json_typeof(field) == AST_JSON_ARRAY) {
+			/* Multiple param passed as array */
+			size_t i;
+			args->media_count = ast_json_array_size(field);
+			args->media = ast_malloc(sizeof(*args->media) * args->media_count);
+
+			if (!args->media) {
+				return -1;
+			}
+
+			for (i = 0; i < args->media_count; ++i) {
+				args->media[i] = ast_json_string_get(ast_json_array_get(field, i));
+			}
+		} else {
+			/* Multiple param passed as single value */
+			args->media_count = 1;
+			args->media = ast_malloc(sizeof(*args->media) * args->media_count);
+			if (!args->media) {
+				return -1;
+			}
+			args->media[0] = ast_json_string_get(field);
+		}
 	}
 	field = ast_json_object_get(body, "lang");
 	if (field) {
@@ -978,7 +1003,47 @@ static void ast_ari_bridges_play_cb(
 
 	for (i = get_params; i; i = i->next) {
 		if (strcmp(i->name, "media") == 0) {
-			args.media = (i->value);
+			/* Parse comma separated list */
+			char *vals[MAX_VALS];
+			size_t j;
+
+			args.media_parse = ast_strdup(i->value);
+			if (!args.media_parse) {
+				ast_ari_response_alloc_failed(response);
+				goto fin;
+			}
+
+			if (strlen(args.media_parse) == 0) {
+				/* ast_app_separate_args can't handle "" */
+				args.media_count = 1;
+				vals[0] = args.media_parse;
+			} else {
+				args.media_count = ast_app_separate_args(
+					args.media_parse, ',', vals,
+					ARRAY_LEN(vals));
+			}
+
+			if (args.media_count == 0) {
+				ast_ari_response_alloc_failed(response);
+				goto fin;
+			}
+
+			if (args.media_count >= MAX_VALS) {
+				ast_ari_response_error(response, 400,
+					"Bad Request",
+					"Too many values for media");
+				goto fin;
+			}
+
+			args.media = ast_malloc(sizeof(*args.media) * args.media_count);
+			if (!args.media) {
+				ast_ari_response_alloc_failed(response);
+				goto fin;
+			}
+
+			for (j = 0; j < args.media_count; ++j) {
+				args.media[j] = (vals[j]);
+			}
 		} else
 		if (strcmp(i->name, "lang") == 0) {
 			args.lang = (i->value);
@@ -1051,6 +1116,8 @@ static void ast_ari_bridges_play_cb(
 #endif /* AST_DEVMODE */
 
 fin: __attribute__((unused))
+	ast_free(args.media_parse);
+	ast_free(args.media);
 	return;
 }
 int ast_ari_bridges_play_with_id_parse_body(
@@ -1061,7 +1128,32 @@ int ast_ari_bridges_play_with_id_parse_body(
 	/* Parse query parameters out of it */
 	field = ast_json_object_get(body, "media");
 	if (field) {
-		args->media = ast_json_string_get(field);
+		/* If they were silly enough to both pass in a query param and a
+		 * JSON body, free up the query value.
+		 */
+		ast_free(args->media);
+		if (ast_json_typeof(field) == AST_JSON_ARRAY) {
+			/* Multiple param passed as array */
+			size_t i;
+			args->media_count = ast_json_array_size(field);
+			args->media = ast_malloc(sizeof(*args->media) * args->media_count);
+
+			if (!args->media) {
+				return -1;
+			}
+
+			for (i = 0; i < args->media_count; ++i) {
+				args->media[i] = ast_json_string_get(ast_json_array_get(field, i));
+			}
+		} else {
+			/* Multiple param passed as single value */
+			args->media_count = 1;
+			args->media = ast_malloc(sizeof(*args->media) * args->media_count);
+			if (!args->media) {
+				return -1;
+			}
+			args->media[0] = ast_json_string_get(field);
+		}
 	}
 	field = ast_json_object_get(body, "lang");
 	if (field) {
@@ -1100,7 +1192,47 @@ static void ast_ari_bridges_play_with_id_cb(
 
 	for (i = get_params; i; i = i->next) {
 		if (strcmp(i->name, "media") == 0) {
-			args.media = (i->value);
+			/* Parse comma separated list */
+			char *vals[MAX_VALS];
+			size_t j;
+
+			args.media_parse = ast_strdup(i->value);
+			if (!args.media_parse) {
+				ast_ari_response_alloc_failed(response);
+				goto fin;
+			}
+
+			if (strlen(args.media_parse) == 0) {
+				/* ast_app_separate_args can't handle "" */
+				args.media_count = 1;
+				vals[0] = args.media_parse;
+			} else {
+				args.media_count = ast_app_separate_args(
+					args.media_parse, ',', vals,
+					ARRAY_LEN(vals));
+			}
+
+			if (args.media_count == 0) {
+				ast_ari_response_alloc_failed(response);
+				goto fin;
+			}
+
+			if (args.media_count >= MAX_VALS) {
+				ast_ari_response_error(response, 400,
+					"Bad Request",
+					"Too many values for media");
+				goto fin;
+			}
+
+			args.media = ast_malloc(sizeof(*args.media) * args.media_count);
+			if (!args.media) {
+				ast_ari_response_alloc_failed(response);
+				goto fin;
+			}
+
+			for (j = 0; j < args.media_count; ++j) {
+				args.media[j] = (vals[j]);
+			}
 		} else
 		if (strcmp(i->name, "lang") == 0) {
 			args.lang = (i->value);
@@ -1173,6 +1305,8 @@ static void ast_ari_bridges_play_with_id_cb(
 #endif /* AST_DEVMODE */
 
 fin: __attribute__((unused))
+	ast_free(args.media_parse);
+	ast_free(args.media);
 	return;
 }
 int ast_ari_bridges_record_parse_body(