ari/pjsip: Make it possible to control transfers through ARI

Introduce a ChannelTransfer event and the ability to notify progress to
ARI. Implement emitting this event from the PJSIP channel instead of
handling the transfer in Asterisk when configured.

Introduce a dialplan function to the PJSIP channel to switch between the
"core" and "ari-only" behavior.

UserNote: Call transfers on the PJSIP channel can now be controlled by
ARI. This can be enabled by using the PJSIP_TRANSFER_HANDLING(ari-only)
dialplan function.

rest-api/api-docs/channels.json

@@ -1997,6 +1997,59 @@
 					]
 				}
 			]
+		},
+		{
+			"path": "/channels/{channelId}/transfer_progress",
+			"description": "Inform the channel that the transfer is in progress.",
+			"operations": [
+				{
+					"httpMethod": "POST",
+					"since": [
+						"22.3.0",
+						"21.8.0",
+						"20.13.0"
+					],
+					"summary": "Inform the channel about the progress of the attended/blind transfer.",
+					"nickname": "transfer_progress",
+					"responseClass": "void",
+					"parameters": [
+						{
+							"name": "channelId",
+							"description": "Channel's id",
+							"paramType": "path",
+							"required": true,
+							"allowMultiple": false,
+							"dataType": "string"
+						},
+						{
+							"name": "states",
+							"description": "The state of the progress",
+							"paramType": "query",
+							"required": true,
+							"allowMultiple": false,
+							"dataType": "string"
+						}
+					],
+					"errorResponses": [
+						{
+							"code": 400,
+							"reason": "Endpoint parameter not provided"
+						},
+						{
+							"code": 404,
+							"reason": "Channel or endpoint not found"
+						},
+						{
+							"code": 409,
+							"reason": "Channel not in a Stasis application"
+						},
+						{
+							"code": 412,
+							"reason": "Channel in invalid state"
+						}
+					]
+				}
+			]
 		}
 	],
 	"models": {

rest-api/api-docs/events.json

@@ -199,7 +199,8 @@
 				"StasisStart",
 				"TextMessageReceived",
 				"ChannelConnectedLine",
-				"PeerStatusChange"
+				"PeerStatusChange",
+				"ChannelTransfer"
 			]
 		},
 		"ContactInfo": {
@@ -934,6 +935,110 @@
 					"description": "The channel whose connected line has changed."
 				}
 			}
+		},
+		"ChannelTransfer": {
+			"id": "ChannelTransfer",
+			"description": "transfer on a channel.",
+			"properties": {
+				"state": {
+					"required": false,
+					"type": "string",
+					"description": "Transfer State"
+				},
+				"refer_to": {
+					"required": true,
+					"type": "ReferTo",
+					"description": "Refer-To information with optionally both affected channels"
+				},
+				"referred_by": {
+					"required": true,
+					"type": "ReferredBy",
+					"description": "Referred-By SIP Header according rfc3892"
+				}
+			}
+		},
+		"ReferTo": {
+			"id": "ReferTo",
+			"description": "transfer destination requested by transferee",
+			"properties": {
+				"requested_destination": {
+					"required": true,
+					"type": "RequiredDestination"
+				},
+				"destination_channel": {
+					"required": false,
+					"type": "Channel",
+					"description": "The Channel Object, that is to be replaced"
+				},
+				"connected_channel": {
+					"required": false,
+					"type": "Channel",
+					"description": "Channel, connected to the to be replaced channel"
+				},
+				"bridge": {
+					"required": false,
+					"type": "Bridge",
+					"description": "Bridge connecting both destination channels"
+				}
+			}
+		},
+		"ReferredBy": {
+			"id": "ReferredBy",
+			"description": "transfer destination requested by transferee",
+			"properties": {
+				"source_channel": {
+					"required": true,
+					"type": "Channel",
+					"description": "The channel on which the refer was received"
+				},
+				"connected_channel": {
+					"required": false,
+					"type": "Channel",
+					"description": "Channel, Connected to the channel, receiving the transfer request on."
+				},
+				"bridge": {
+					"required": false,
+					"type": "Bridge",
+					"description": "Bridge connecting both Channels"
+				}
+			}
+		},
+		"RequiredDestination": {
+			"id": "RequiredDestination",
+			"description": "Information about the requested destination",
+			"properties": {
+				"protocol_id": {
+					"required": false,
+					"type": "string",
+					"description": "the requested protocol-id by the referee in case of SIP channel, this is a SIP Call ID, Mutually exclusive to destination"
+				},
+				"destination": {
+					"required": false,
+					"type": "string",
+					"description": "Destination User Part. Only for Blind transfer. Mutually exclusive to protocol_id"
+				},
+				"additional_protocol_params": {
+					"required": false,
+					"type": "List[AdditionalParam]",
+					"description": "List of additional protocol specific information"
+				}
+			}
+		},
+		"AdditionalParam": {
+			"id": "AdditionalParam",
+			"description": "Protocol specific additional parameter",
+			"properties": {
+				"parameter_name": {
+					"required": true,
+					"type": "string",
+					"description": "Name of the parameter"
+				},
+				"parameter_value": {
+					"required": true,
+					"type": "string",
+					"description": "Value of the parameter"
+				}
+			}
 		}
 	}
 }