uniqueid: channel linkedid, ami, ari object creation with id's

Much needed was a way to assign id to objects on creation, and
much change was necessary to accomplish it.  Channel uniqueids
and linkedids are split into separate string and creation time
components without breaking linkedid propgation.  This allowed
the uniqueid to be specified by the user interface - and those
values are now carried through to channel creation, adding the
assignedids value to every function in the chain including the
channel drivers. For local channels, the second channel can be
specified or left to default to a ;2 suffix of first.  In ARI,
bridge, playback, and snoop objects can also be created with a
specified uniqueid.

Along the way, the args order to allocating channels was fixed
in chan_mgcp and chan_gtalk, and linkedid is no longer lost as
masquerade occurs.

(closes issue ASTERISK-23120)
Review: https://reviewboard.asterisk.org/r/3191/
........

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


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

2 files changed, 352 insertions, 0 deletions

diff --git a/rest-api/api-docs/bridges.json b/rest-api/api-docs/bridges.json
index b259ca8f3..3e899788f 100644
--- a/rest-api/api-docs/bridges.json
+++ b/rest-api/api-docs/bridges.json
@@ -40,6 +40,14 @@
 							}
 						},
 						{
+							"name": "bridgeId",
+							"description": "Unique ID to give to the bridge being created.",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "string"
+						},
+						{
 							"name": "name",
 							"description": "Name to give to the bridge being created.",
 							"paramType": "query",
@@ -56,6 +64,46 @@
 			"description": "Individual bridge",
 			"operations": [
 				{
+					"httpMethod": "POST",
+					"summary": "Create a new bridge or updates an existing one.",
+					"notes": "This bridge persists until it has been shut down, or Asterisk has been shut down.",
+					"nickname": "create_or_update_with_id",
+					"responseClass": "Bridge",
+					"parameters": [
+						{
+							"name": "type",
+							"description": "Set the type of bridge.",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "string",
+							"allowableValues": {
+								"valueType": "LIST",
+								"values": [
+									"mixing",
+									"holding"
+								]
+							}
+						},
+						{
+							"name": "bridgeId",
+							"description": "Unique ID to give to the bridge being created.",
+							"paramType": "path",
+							"required": true,
+							"allowMultiple": false,
+							"dataType": "string"
+						},
+						{
+							"name": "name",
+							"description": "Set the name of the bridge.",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "string"
+						}
+					]
+				},
+				{
 					"httpMethod": "GET",
 					"summary": "Get bridge details.",
 					"nickname": "get",
diff --git a/rest-api/api-docs/channels.json b/rest-api/api-docs/channels.json
index 0cfe90e5f..df90a4fb2 100644
--- a/rest-api/api-docs/channels.json
+++ b/rest-api/api-docs/channels.json
@@ -96,6 +96,22 @@
 							"required": false,
 							"dataType": "containers",
 							"allowMultiple": false
+						},
+						{
+							"name": "channelId",
+							"description": "The unique id to assign the channel on creation.",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "string"
+						},
+						{
+							"name": "otherChannelId",
+							"description": "The unique id to assign the second channel when using local channels.",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "string"
 						}
 					],
 					"errorResponses": [
@@ -134,6 +150,111 @@
 					]
 				},
 				{
+					"httpMethod": "POST",
+					"summary": "Create a new channel (originate with id).",
+					"notes": "The new channel is created immediately and a snapshot of it returned. If a Stasis application is provided it will be automatically subscribed to the originated channel for further events and updates.",
+					"nickname": "originateWithId",
+					"responseClass": "Channel",
+					"parameters": [
+						{
+							"name": "channelId",
+							"description": "The unique id to assign the channel on creation.",
+							"paramType": "path",
+							"required": true,
+							"allowMultiple": false,
+							"dataType": "string"
+						},
+						{
+							"name": "endpoint",
+							"description": "Endpoint to call.",
+							"paramType": "query",
+							"required": true,
+							"allowMultiple": false,
+							"dataType": "string"
+						},
+						{
+							"name": "extension",
+							"description": "The extension to dial after the endpoint answers",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "string"
+						},
+						{
+							"name": "context",
+							"description": "The context to dial after the endpoint answers. If omitted, uses 'default'",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "string"
+						},
+						{
+							"name": "priority",
+							"description": "The priority to dial after the endpoint answers. If omitted, uses 1",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "long"
+						},
+						{
+							"name": "app",
+							"description": "The application that is subscribed to the originated channel, and passed to the Stasis application.",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "string"
+						},
+						{
+							"name": "appArgs",
+							"description": "The application arguments to pass to the Stasis application.",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "string"
+						},
+						{
+							"name": "callerId",
+							"description": "CallerID to use when dialing the endpoint or extension.",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "string"
+						},
+						{
+							"name": "timeout",
+							"description": "Timeout (in seconds) before giving up dialing, or -1 for no timeout.",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "int",
+							"defaultValue": 30
+						},
+						{
+							"name": "variables",
+							"description": "The 'variables' key in the body object holds variable key/value pairs to set on the channel on creation. Other keys in the body object are interpreted as query parameters. Ex. { 'endpoint': 'SIP/Alice', 'variables': { 'CALLERID(name)': 'Alice' } }",
+							"paramType": "body",
+							"required": false,
+							"dataType": "containers",
+							"allowMultiple": false
+						},
+						{
+							"name": "otherChannelId",
+							"description": "The unique id to assign the second channel when using local channels.",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "string"
+						}
+					],
+					"errorResponses": [
+						{
+							"code": 400,
+							"reason": "Invalid parameters for originating a channel."
+						}
+					]
+
+				},
+				{
 					"httpMethod": "DELETE",
 					"summary": "Delete (i.e. hangup) a channel.",
 					"nickname": "hangup",
@@ -731,6 +852,88 @@
 							"allowMultiple": false,
 							"dataType": "int",
 							"defaultValue": 3000
+						},
+						{
+							"name": "playbackId",
+							"description": "Playback ID.",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "string"
+						}
+					],
+					"errorResponses": [
+						{
+							"code": 404,
+							"reason": "Channel not found"
+						},
+						{
+							"code": 409,
+							"reason": "Channel not in a Stasis application"
+						}
+					]
+				}
+			]
+		},
+		{
+			"path": "/channels/{channelId}/play/{playbackId}",
+			"description": "Play media to a channel",
+			"operations": [
+				{
+					"httpMethod": "POST",
+					"summary": "Start playback of media and specify the playbackId.",
+					"notes": "The media URI may be any of a number of URI's. Currently sound: and recording: URI's are supported. This operation creates a playback resource that can be used to control the playback of media (pause, rewind, fast forward, etc.)",
+					"nickname": "playWithId",
+					"responseClass": "Playback",
+					"parameters": [
+						{
+							"name": "channelId",
+							"description": "Channel's id",
+							"paramType": "path",
+							"required": true,
+							"allowMultiple": false,
+							"dataType": "string"
+						},
+						{
+							"name": "playbackId",
+							"description": "Playback 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"
+						},
+						{
+							"name": "skipms",
+							"description": "Number of milliseconds to skip for forward/reverse operations.",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "int",
+							"defaultValue": 3000
 						}
 					],
 					"errorResponses": [
@@ -1033,6 +1236,107 @@
 							"required": false,
 							"allowMultiple": false,
 							"dataType": "string"
+						},
+						{
+							"name": "snoopId",
+							"description": "Unique ID to assign to snooping channel",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "string"
+						}
+					],
+					"errorResponses": [
+						{
+							"code": 400,
+							"reason": "Invalid parameters"
+						},
+						{
+							"code": 404,
+							"reason": "Channel not found"
+						}
+					]
+				}
+			]
+		},
+		{
+			"path": "/channels/{channelId}/snoop/{snoopId}",
+			"description": "Snoop (spy/whisper) on a channel",
+			"operations": [
+				{
+					"httpMethod": "POST",
+					"summary": "Start snooping.",
+					"notes": "Snoop (spy/whisper) on a specific channel.",
+					"nickname": "snoopChannelWithId",
+					"responseClass": "Channel",
+					"parameters": [
+						{
+							"name": "channelId",
+							"description": "Channel's id",
+							"paramType": "path",
+							"required": true,
+							"allowMultiple": false,
+							"dataType": "string"
+						},
+						{
+							"name": "snoopId",
+							"description": "Unique ID to assign to snooping channel",
+							"paramType": "path",
+							"required": true,
+							"allowMultiple": false,
+							"dataType": "string"
+						},
+						{
+							"name": "spy",
+							"description": "Direction of audio to spy on",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "string",
+							"defaultValue": "none",
+							"allowableValues": {
+								"valueType": "LIST",
+								"values": [
+									"none",
+									"both",
+									"out",
+									"in"
+								]
+							}
+						},
+						{
+							"name": "whisper",
+							"description": "Direction of audio to whisper into",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "string",
+							"defaultValue": "none",
+							"allowableValues": {
+								"valueType": "LIST",
+								"values": [
+									"none",
+									"both",
+									"out",
+									"in"
+								]
+							}
+						},
+						{
+							"name": "app",
+							"description": "Application the snooping channel is placed into",
+							"paramType": "query",
+							"required": true,
+							"allowMultiple": false,
+							"dataType": "string"
+						},
+						{
+							"name": "appArgs",
+							"description": "The application arguments to pass to the Stasis application",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "string"
 						}
 					],
 					"errorResponses": [