From ac0289e710ec51bd318cf9781d74ac74dd44d911 Mon Sep 17 00:00:00 2001
From: Andre Weinand <aweinand@microsoft.com>
Date: Tue, 12 Feb 2019 11:37:32 +0100
Subject: [PATCH] first cut of open-external-request

---
 _data/specification-toc.yml |  2 ++
 debugAdapterProtocol.json   | 38 ++++++++++++++++++++++++++++++
 specification.md            | 47 +++++++++++++++++++++++++++++++++----
 3 files changed, 82 insertions(+), 5 deletions(-)

diff --git a/_data/specification-toc.yml b/_data/specification-toc.yml
index 20c5050..b6aa4fb 100644
--- a/_data/specification-toc.yml
+++ b/_data/specification-toc.yml
@@ -114,6 +114,8 @@
   - title: Reverse Requests
     anchor: Reverse_Requests
     children:
+    - title: OpenExternal
+      anchor: Reverse_Requests_OpenExternal
     - title: RunInTerminal
       anchor: Reverse_Requests_RunInTerminal
   - title: Types
diff --git a/debugAdapterProtocol.json b/debugAdapterProtocol.json
index 86117e2..563c3a7 100644
--- a/debugAdapterProtocol.json
+++ b/debugAdapterProtocol.json
@@ -566,6 +566,40 @@
 			}]
 		},
 
+		"OpenExternalRequest": {
+			"allOf": [ { "$ref": "#/definitions/Request" }, {
+				"type": "object",
+				"description": "This request is sent from the debug adapter to the client to open a url in an external program, e.g. a http(s) or mailto-link, using the default application.",
+				"properties": {
+					"command": {
+						"type": "string",
+						"enum": [ "openExternal" ]
+					},
+					"arguments": {
+						"$ref": "#/definitions/OpenExternalArguments"
+					}
+				},
+				"required": [ "command", "arguments" ]
+			}]
+		},
+		"OpenExternalArguments": {
+			"type": "object",
+			"description": "Arguments for 'openExternal' request.",
+			"properties": {
+				"url": {
+					"type": "string",
+					"description": "The uri that should be opened."
+				}
+			},
+			"required": [ "url" ]
+		},
+		"OpenExternalResponse": {
+			"allOf": [ { "$ref": "#/definitions/Response" }, {
+				"type": "object",
+				"description": "Response to 'openExternal' request. This is just an acknowledgement, so no body field is required."
+			}]
+		},
+
 		"InitializeRequest": {
 			"allOf": [ { "$ref": "#/definitions/Request" }, {
 				"type": "object",
@@ -627,6 +661,10 @@
 				"supportsRunInTerminalRequest": {
 					"type": "boolean",
 					"description": "Client supports the runInTerminal request."
+				},
+				"supportsOpenExternalRequest": {
+					"type": "boolean",
+					"description": "Client supports the openExternal request."
 				}
 			},
 			"required": [ "adapterID" ]
diff --git a/specification.md b/specification.md
index 3a0002d..8b451a9 100644
--- a/specification.md
+++ b/specification.md
@@ -159,7 +159,7 @@ interface StoppedEvent extends Event {
     /**
      * The reason for the event.
      * For backward compatibility this string is shown in the UI if the 'description' attribute is missing (but it must not be translated).
-     * Values: 'step', 'breakpoint', 'exception', 'pause', 'entry', 'goto', etc.
+     * Values: 'step', 'breakpoint', 'exception', 'pause', 'entry', 'goto', 'function breakpoint', etc.
      */
     reason: string;
 
@@ -515,6 +515,38 @@ interface RunInTerminalResponse extends Response {
 }
 ```
 
+### <a name="Reverse_Requests_OpenExternal" class="anchor"></a>:leftwards_arrow_with_hook: OpenExternal Request
+
+This request is sent from the debug adapter to the client to open a url in an external program, e.g. a http(s) or mailto-link, using the default application.
+
+```typescript
+interface OpenExternalRequest extends Request {
+  command: 'openExternal';
+
+  arguments: OpenExternalArguments;
+}
+```
+
+Arguments for 'openExternal' request.
+
+<a name="Types_OpenExternalArguments" class="anchor"></a>
+```typescript
+interface OpenExternalArguments {
+  /**
+   * The uri that should be opened.
+   */
+  url: string;
+}
+```
+
+Response to 'openExternal' request. This is just an acknowledgement, so no body field is required.
+
+<a name="Types_OpenExternalResponse" class="anchor"></a>
+```typescript
+interface OpenExternalResponse extends Response {
+}
+```
+
 ## <a name="Requests" class="anchor"></a>Requests
 
 ### <a name="Requests_Initialize" class="anchor"></a>:leftwards_arrow_with_hook: Initialize Request
@@ -588,6 +620,11 @@ interface InitializeRequestArguments {
    * Client supports the runInTerminal request.
    */
   supportsRunInTerminalRequest?: boolean;
+
+  /**
+   * Client supports the openExternal request.
+   */
+  supportsOpenExternalRequest?: boolean;
 }
 ```
 
@@ -876,11 +913,11 @@ interface SetBreakpointsResponse extends Response {
 
 ### <a name="Requests_SetFunctionBreakpoints" class="anchor"></a>:leftwards_arrow_with_hook: SetFunctionBreakpoints Request
 
-Sets multiple function breakpoints and clears all previous function breakpoints.
+Replaces all existing function breakpoints with new function breakpoints.
 
-To clear all function breakpoint, specify an empty array.
+To clear all function breakpoints, specify an empty array.
 
-When a function breakpoint is hit, a 'stopped' event (event type 'function breakpoint') is generated.
+When a function breakpoint is hit, a 'stopped' event (with reason 'function breakpoint') is generated.
 
 ```typescript
 interface SetFunctionBreakpointsRequest extends Request {
@@ -1465,7 +1502,7 @@ interface SetVariableArguments {
   variablesReference: number;
 
   /**
-   * The name of the variable.
+   * The name of the variable in the container.
    */
   name: string;