API: UriHandler, rename and docs

extensions/git/src/protocolHandler.ts

@@ -5,16 +5,16 @@
 
 'use strict';
 
-import { ProtocolHandler, Uri, window, Disposable, commands } from 'vscode';
+import { UriHandler, Uri, window, Disposable, commands } from 'vscode';
 import { dispose } from './util';
 import * as querystring from 'querystring';
 
-export class GitProtocolHandler implements ProtocolHandler {
+export class GitProtocolHandler implements UriHandler {
 
 	private disposables: Disposable[] = [];
 
 	constructor() {
-		this.disposables.push(window.registerProtocolHandler(this));
+		this.disposables.push(window.registerUriHandler(this));
 	}
 
 	handleUri(uri: Uri): void {

src/vs/vscode.proposed.d.ts

@@ -497,16 +497,42 @@ declare module 'vscode' {
 
 	//#region URLs
 
-	export interface ProtocolHandler {
+	/**
+	 * A Uri handler is responsible for handling system-wide [Uris](#Uri).
+	 *
+	 * @see [window.registerUriHandler](#window.registerUriHandler).
+	 */
+	export interface UriHandler {
+
+		/**
+		 * Handle the provided system-wide [Uri](#Uri).
+		 *
+		 * @see [window.registerUriHandler](#window.registerUriHandler).
+		 */
 		handleUri(uri: Uri): void;
 	}
 
 	export namespace window {
 
 		/**
-		 * Registers a protocol handler capable of handling system-wide URIs.
+		 * Registers a [Uri handler](#UriHandler) capable of handling system-wide [Uris](#Uri).
+		 * A Uri handler is scoped to the extension it is contributed from: it will only
+		 * be able to handle Uris which are directed to the extension itself.
+		 *
+		 * For example, if the `vscode.git` extension registers a Uri handler, it will only
+		 * be allowed to handle Uris with the prefix `{scheme}://vscode.git`, in which `{scheme}`
+		 * is either `vscode` or `vscode-insiders`. All the following Uris are examples:
+		 *
+		 * - `vscode://vscode.git`
+		 * - `vscode://vscode.git/`
+		 * - `vscode-insiders://vscode.git/status`
+		 * - `vscode-insiders://vscode.git/clone?url=foobar`
+		 *
+		 * An extension can only register a single Uri handler in its entire activation lifetime.
+		 *
+		 * @param handler The Uri handler to register for this extension.
 		 */
-		export function registerProtocolHandler(handler: ProtocolHandler): Disposable;
+		export function registerUriHandler(handler: UriHandler): Disposable;
 	}
 
 	//#endregion

src/vs/workbench/api/electron-browser/mainThreadUrls.ts

@@ -42,7 +42,7 @@ export class MainThreadUrls implements MainThreadUrlsShape {
 		this.proxy = context.getProxy(ExtHostContext.ExtHostUrls);
 	}
 
-	$registerProtocolHandler(handle: number, extensionId: string): TPromise<void> {
+	$registerUriHandler(handle: number, extensionId: string): TPromise<void> {
 		const handler = new ExtensionUrlHandler(this.proxy, handle, extensionId);
 		const disposable = this.urlService.registerHandler(handler);
 
@@ -52,7 +52,7 @@ export class MainThreadUrls implements MainThreadUrlsShape {
 		return TPromise.as(null);
 	}
 
-	$unregisterProtocolHandler(handle: number): TPromise<void> {
+	$unregisterUriHandler(handle: number): TPromise<void> {
 		const tuple = this.handlers.get(handle);
 
 		if (!tuple) {

src/vs/workbench/api/node/extHost.api.impl.ts

@@ -452,8 +452,8 @@ export function createApiFactory(
 			registerWebviewPanelSerializer: proposedApiFunction(extension, (viewType: string, serializer: vscode.WebviewPanelSerializer) => {
 				return extHostWebviews.registerWebviewPanelSerializer(viewType, serializer);
 			}),
-			registerProtocolHandler: proposedApiFunction(extension, (handler: vscode.ProtocolHandler) => {
-				return extHostUrls.registerProtocolHandler(extension.id, handler);
+			registerUriHandler: proposedApiFunction(extension, (handler: vscode.UriHandler) => {
+				return extHostUrls.registerUriHandler(extension.id, handler);
 			}),
 			get quickInputBackButton() {
 				return proposedApiFunction(extension, (): vscode.QuickInputButton => {

src/vs/workbench/api/node/extHost.protocol.ts

@@ -462,8 +462,8 @@ export interface ExtHostWebviewsShape {
 }
 
 export interface MainThreadUrlsShape extends IDisposable {
-	$registerProtocolHandler(handle: number, extensionId: string): TPromise<void>;
-	$unregisterProtocolHandler(handle: number): TPromise<void>;
+	$registerUriHandler(handle: number, extensionId: string): TPromise<void>;
+	$unregisterUriHandler(handle: number): TPromise<void>;
 }
 
 export interface ExtHostUrlsShape {

src/vs/workbench/api/node/extHostUrls.ts

@@ -15,7 +15,7 @@ export class ExtHostUrls implements ExtHostUrlsShape {
 	private readonly _proxy: MainThreadUrlsShape;
 
 	private handles = new Set<string>();
-	private handlers = new Map<number, vscode.ProtocolHandler>();
+	private handlers = new Map<number, vscode.UriHandler>();
 
 	constructor(
 		mainContext: IMainContext
@@ -23,7 +23,7 @@ export class ExtHostUrls implements ExtHostUrlsShape {
 		this._proxy = mainContext.getProxy(MainContext.MainThreadUrls);
 	}
 
-	registerProtocolHandler(extensionId: string, handler: vscode.ProtocolHandler): vscode.Disposable {
+	registerUriHandler(extensionId: string, handler: vscode.UriHandler): vscode.Disposable {
 		if (this.handles.has(extensionId)) {
 			throw new Error(`Protocol handler already registered for extension ${extensionId}`);
 		}
@@ -31,12 +31,12 @@ export class ExtHostUrls implements ExtHostUrlsShape {
 		const handle = ExtHostUrls.HandlePool++;
 		this.handles.add(extensionId);
 		this.handlers.set(handle, handler);
-		this._proxy.$registerProtocolHandler(handle, extensionId);
+		this._proxy.$registerUriHandler(handle, extensionId);
 
 		return toDisposable(() => {
 			this.handles.delete(extensionId);
 			this.handlers.delete(handle);
-			this._proxy.$unregisterProtocolHandler(handle);
+			this._proxy.$unregisterUriHandler(handle);
 		});
 	}