ARI: Bridge Playback, Bridge Record

Adds a new channel driver for creating channels for specific purposes
in bridges, primarily to act as either recorders or announcers. Adds
ARI commands for playing announcements to ever participant in a bridge
as well as for recording a bridge. This patch also includes some
documentation/reponse fixes to related ARI models such as playback
controls.

(closes issue ASTERISK-21592)
Reported by: Matt Jordan

(closes issue ASTERISK-21593)
Reported by: Matt Jordan

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


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

rest-api/api-docs/bridges.json

@@ -168,6 +168,83 @@
 				}
 			]
 		},
+		{
+			"path": "/bridges/{bridgeId}/play",
+			"description": "Play media to the participants of a bridge",
+			"operations": [
+				{
+					"httpMethod": "POST",
+					"summary": "Start playback of media on a bridge.",
+					"notes": "The media URI may be any of a number of URI's. You may use http: and https: URI's, as well as sound: and recording: URI's. This operation creates a playback resource that can be used to control the playback of media (pause, rewind, fast forward, etc.)",
+					"nickname": "playOnBridge",
+					"responseClass": "Playback",
+					"parameters": [
+						{
+							"name": "bridgeId",
+							"description": "Bridge's id",
+							"paramType": "path",
+							"required": true,
+							"allowMultiple": false,
+							"dataType": "string"
+						},
+						{
+							"name": "media",
+							"description": "Media's URI to play.",
+							"paramType": "query",
+							"required": true,
+							"allowMultiple": false,
+							"dataType": "string"
+						},
+						{
+							"name": "lang",
+							"description": "For sounds, selects language for sound.",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "string"
+						},
+						{
+							"name": "offsetms",
+							"description": "Number of media to skip before playing.",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "int",
+							"defaultValue": 0,
+							"allowableValues": {
+								"valueType": "RANGE",
+								"min": 0
+							}
+
+						},
+						{
+							"name": "skipms",
+							"description": "Number of milliseconds to skip for forward/reverse operations.",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "int",
+							"defaultValue": 3000,
+							"allowableValues": {
+								"valueType": "RANGE",
+								"min": 0
+							}
+
+						}
+					],
+					"errorResponses": [
+						{
+							"code": 404,
+							"reason": "Bridge not found"
+						},
+						{
+							"code": 409,
+							"reason": "Bridge not in a Stasis application"
+						}
+					]
+				}
+			]
+		},
 		{
 			"path": "/bridges/{bridgeId}/record",
 			"description": "Record audio on a bridge",
@@ -195,6 +272,14 @@
 							"allowMultiple": false,
 							"dataType": "string"
 						},
+						{
+							"name": "format",
+							"description": "Format to encode audio in",
+							"paramType": "query",
+							"required": true,
+							"allowMultiple": true,
+							"dataType": "string"
+						},
 						{
 							"name": "maxDurationSeconds",
 							"description": "Maximum duration of the recording, in seconds. 0 for no limit.",
@@ -202,7 +287,11 @@
 							"required": false,
 							"allowMultiple": false,
 							"dataType": "int",
-							"defaultValue": 0
+							"defaultValue": 0,
+							"allowableValues": {
+								"valueType": "RANGE",
+								"min": 0
+							}
 						},
 						{
 							"name": "maxSilenceSeconds",
@@ -211,16 +300,28 @@
 							"required": false,
 							"allowMultiple": false,
 							"dataType": "int",
-							"defaultValue": 0
+							"defaultValue": 0,
+							"allowableValues": {
+								"valueType": "RANGE",
+								"min": 0
+							}
 						},
 						{
-							"name": "append",
-							"description": "If true, and recording already exists, append to recording.",
+							"name": "ifExists",
+							"description": "Action to take if a recording with the same name already exists.",
 							"paramType": "query",
 							"required": false,
 							"allowMultiple": false,
-							"dataType": "boolean",
-							"defaultValue": false
+							"dataType": "string",
+							"defaultValue": "fail",
+							"allowableValues": {
+								"valueType": "LIST",
+								"values": [
+									"fail",
+									"overwrite",
+									"append"
+								]
+							}
 						},
 						{
 							"name": "beep",

rest-api/api-docs/channels.json

@@ -538,7 +538,7 @@
 					"summary": "Start a recording.",
 					"notes": "Record audio from a channel. Note that this will not capture audio sent to the channel. The bridge itself has a record feature if that's what you want.",
 					"nickname": "recordChannel",
-					"responseClass": "void",
+					"responseClass": "LiveRecording",
 					"parameters": [
 						{
 							"name": "channelId",

rest-api/api-docs/playback.json

@@ -53,7 +53,7 @@
 					"httpMethod": "POST",
 					"summary": "Get a playback's details.",
 					"nickname": "controlPlayback",
-					"responseClass": "Playback",
+					"responseClass": "void",
 					"parameters": [
 						{
 							"name": "playbackId",

rest-api/api-docs/recordings.json

@@ -243,7 +243,15 @@
 			"id": "LiveRecording",
 			"description": "A recording that is in progress",
 			"properties": {
-				"id": {
+				"name": {
+					"required": true,
+					"type": "string"
+				},
+				"state": {
+					"required": true,
+					"type": "string"
+				},
+				"format": {
 					"required": true,
 					"type": "string"
 				}