This patch implements the REST API's for POST /channels/{channelId}/play

and GET /playback/{playbackId}.

This allows an external application to initiate playback of a sound on a
channel while the channel is in the Stasis application.

/play commands are issued asynchronously, and return immediately with
the URL of the associated /playback resource. Playback commands queue up,
playing in succession. The /playback resource shows the state of a
playback operation as enqueued, playing or complete. (Although the
operation will only be in the 'complete' state for a very short time,
since it is almost immediately freed up).

(closes issue ASTERISK-21283)
(closes issue ASTERISK-21586)
Review: https://reviewboard.asterisk.org/r/2531/



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

rest-api/api-docs/channels.json

@@ -405,6 +405,14 @@
 							"required": true,
 							"allowMultiple": false,
 							"dataType": "string"
+						},
+						{
+							"name": "lang",
+							"description": "For sounds, selects language for sound",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "string"
 						}
 					],
 					"errorResponses": [
@@ -640,6 +648,44 @@
 					"description": "Timestamp when channel was created"
 				}
 			}
+		},
+		"Playback": {
+			"id": "Playback",
+			"description": "Object representing the playback of media to a channel",
+			"properties": {
+				"id": {
+					"type": "string",
+					"description": "ID for this playback operation",
+					"required": true
+				},
+				"media_uri": {
+					"type": "string",
+					"description": "URI for the media to play back.",
+					"required": true
+				},
+				"target_uri": {
+					"type": "string",
+					"description": "URI for the channel or bridge to play the media on",
+					"required": true
+				},
+				"language": {
+					"type": "string",
+					"description": "For media types that support multiple languages, the language requested for playback."
+				},
+				"state": {
+					"type": "string",
+					"description": "Current state of the playback operation.",
+					"required": true,
+					"allowableValues": {
+						"valueType": "LIST",
+						"values": [
+							"queued",
+							"playing",
+							"complete"
+						]
+					}
+				}
+			}
 		}
 	}
 }

rest-api/api-docs/events.json

@@ -69,7 +69,31 @@
 				"channel_hangup_request": { "type": "ChannelHangupRequest" },
 				"channel_varset": { "type": "ChannelVarset" },
 				"stasis_end": { "type": "StasisEnd" },
-				"stasis_start": { "type": "StasisStart" }
+				"stasis_start": { "type": "StasisStart" },
+				"playback_started": { "type": "PlaybackStarted" },
+				"playback_finished": { "type": "PlaybackFinished" }
+			}
+		},
+		"PlaybackStarted": {
+			"id": "PlaybackStarted",
+			"description": "Event showing the start of a media playback operation.",
+			"properties": {
+				"playback": {
+					"type": "Playback",
+					"description": "Playback control object",
+					"required": true
+				}
+			}
+		},
+		"PlaybackFinished": {
+			"id": "PlaybackFinished",
+			"description": "Event showing the completion of a media playback operation.",
+			"properties": {
+				"playback": {
+					"type": "Playback",
+					"description": "Playback control object",
+					"required": true
+				}
 			}
 		},
 		"ApplicationReplaced": {