From 47326c6b9ad858852f4fd6361cfeb8ebfe48e9e5 Mon Sep 17 00:00:00 2001 From: Andrew Swan Date: Fri, 5 Feb 2016 09:56:37 -0800 Subject: [PATCH] Bug 1245678 - [webext] Add downloads API schema and implementation boilerplate. r=rpl --- toolkit/components/extensions/Extension.jsm | 2 + .../components/extensions/ext-downloads.js | 29 + toolkit/components/extensions/jar.mn | 1 + .../extensions/schemas/downloads.json | 763 ++++++++++++++++++ toolkit/components/extensions/schemas/jar.mn | 1 + .../extensions/test/mochitest/mochitest.ini | 1 + .../test/mochitest/test_ext_downloads.html | 48 ++ 7 files changed, 845 insertions(+) create mode 100644 toolkit/components/extensions/ext-downloads.js create mode 100644 toolkit/components/extensions/schemas/downloads.json create mode 100644 toolkit/components/extensions/test/mochitest/test_ext_downloads.html diff --git a/toolkit/components/extensions/Extension.jsm b/toolkit/components/extensions/Extension.jsm index 0dd123f94b3c..e0d59db43547 100644 --- a/toolkit/components/extensions/Extension.jsm +++ b/toolkit/components/extensions/Extension.jsm @@ -60,6 +60,7 @@ Cu.import("resource://gre/modules/ExtensionManagement.jsm"); ExtensionManagement.registerScript("chrome://extensions/content/ext-alarms.js"); ExtensionManagement.registerScript("chrome://extensions/content/ext-backgroundPage.js"); ExtensionManagement.registerScript("chrome://extensions/content/ext-cookies.js"); +ExtensionManagement.registerScript("chrome://extensions/content/ext-downloads.js"); ExtensionManagement.registerScript("chrome://extensions/content/ext-notifications.js"); ExtensionManagement.registerScript("chrome://extensions/content/ext-i18n.js"); ExtensionManagement.registerScript("chrome://extensions/content/ext-idle.js"); @@ -73,6 +74,7 @@ ExtensionManagement.registerScript("chrome://extensions/content/ext-test.js"); const BASE_SCHEMA = "chrome://extensions/content/schemas/manifest.json"; ExtensionManagement.registerSchema("chrome://extensions/content/schemas/cookies.json"); +ExtensionManagement.registerSchema("chrome://extensions/content/schemas/downloads.json"); ExtensionManagement.registerSchema("chrome://extensions/content/schemas/extension.json"); ExtensionManagement.registerSchema("chrome://extensions/content/schemas/extension_types.json"); ExtensionManagement.registerSchema("chrome://extensions/content/schemas/i18n.json"); diff --git a/toolkit/components/extensions/ext-downloads.js b/toolkit/components/extensions/ext-downloads.js new file mode 100644 index 000000000000..8a319579943f --- /dev/null +++ b/toolkit/components/extensions/ext-downloads.js @@ -0,0 +1,29 @@ +"use strict"; + +var { classes: Cc, interfaces: Ci, utils: Cu } = Components; + +Cu.import("resource://gre/modules/ExtensionUtils.jsm"); +const { + ignoreEvent, +} = ExtensionUtils; + +extensions.registerSchemaAPI("downloads", "downloads", (extension, context) => { + return { + downloads: { + // When we do open(), check for additional downloads.open permission. + // i.e.: + // open(downloadId) { + // if (!extension.hasPermission("downloads.open")) { + // throw new context.cloneScope.Error("Permission denied because 'downloads.open' permission is missing."); + // } + // ... + // } + // likewise for setShelfEnabled() and the "download.shelf" permission + + onCreated: ignoreEvent(context, "downloads.onCreated"), + onErased: ignoreEvent(context, "downloads.onErased"), + onChanged: ignoreEvent(context, "downloads.onChanged"), + onDeterminingFilename: ignoreEvent(context, "downloads.onDeterminingFilename"), + }, + }; +}); diff --git a/toolkit/components/extensions/jar.mn b/toolkit/components/extensions/jar.mn index 51596c5d5849..fedddd873f98 100644 --- a/toolkit/components/extensions/jar.mn +++ b/toolkit/components/extensions/jar.mn @@ -7,6 +7,7 @@ toolkit.jar: content/extensions/ext-alarms.js content/extensions/ext-backgroundPage.js content/extensions/ext-cookies.js + content/extensions/ext-downloads.js content/extensions/ext-notifications.js content/extensions/ext-i18n.js content/extensions/ext-idle.js diff --git a/toolkit/components/extensions/schemas/downloads.json b/toolkit/components/extensions/schemas/downloads.json new file mode 100644 index 000000000000..2482aa358925 --- /dev/null +++ b/toolkit/components/extensions/schemas/downloads.json @@ -0,0 +1,763 @@ +[ + { + "namespace": "manifest", + "types": [ + { + "$extend": "Permission", + "choices": [{ + "type": "string", + "enum": [ + "downloads", + "downloads.open", + "downloads.shelf" + ] + }] + } + ] + }, + { + "namespace": "downloads", + "types": [ + { + "id": "FilenameConflictAction", + "type": "string", + "enum": [ + "uniqify", + "overwrite", + "prompt" + ] + }, + { + "id": "InterruptReason", + "type": "string", + "enum": [ + "FILE_FAILED", + "FILE_ACCESS_DENIED", + "FILE_NO_SPACE", + "FILE_NAME_TOO_LONG", + "FILE_TOO_LARGE", + "FILE_VIRUS_INFECTED", + "FILE_TRANSIENT_ERROR", + "FILE_BLOCKED", + "FILE_SECURITY_CHECK_FAILED", + "FILE_TOO_SHORT", + "NETWORK_FAILED", + "NETWORK_TIMEOUT", + "NETWORK_DISCONNECTED", + "NETWORK_SERVER_DOWN", + "NETWORK_INVALID_REQUEST", + "SERVER_FAILED", + "SERVER_NO_RANGE", + "SERVER_BAD_CONTENT", + "SERVER_UNAUTHORIZED", + "SERVER_CERT_PROBLEM", + "SERVER_FORBIDDEN", + "USER_CANCELED", + "USER_SHUTDOWN", + "CRASH" + ] + }, + { + "id": "DangerType", + "type": "string", + "enum": [ + "file", + "url", + "content", + "uncommon", + "host", + "unwanted", + "safe", + "accepted" + ], + "description": "
file
The download's filename is suspicious.
url
The download's URL is known to be malicious.
content
The downloaded file is known to be malicious.
uncommon
The download's URL is not commonly downloaded and could be dangerous.
safe
The download presents no known danger to the user's computer.
These string constants will never change, however the set of DangerTypes may change." + }, + { + "id": "State", + "type": "string", + "enum": [ + "in_progress", + "interrupted", + "complete" + ], + "description": "
in_progress
The download is currently receiving data from the server.
interrupted
An error broke the connection with the file host.
complete
The download completed successfully.
These string constants will never change, however the set of States may change." + }, + { + "id": "DownloadItem", + "type": "object", + "properties": { + "id": { + "description": "An identifier that is persistent across browser sessions.", + "type": "integer" + }, + "url": { + "description": "Absolute URL.", + "type": "string" + }, + "referrer": { + "type": "string" + }, + "filename": { + "description": "Absolute local path.", + "type": "string" + }, + "incognito": { + "description": "False if this download is recorded in the history, true if it is not recorded.", + "type": "boolean" + }, + "danger": { + "$ref": "DangerType", + "description": "Indication of whether this download is thought to be safe or known to be suspicious." + }, + "mime": { + "description": "The file's MIME type.", + "type": "string" + }, + "startTime": { + "description": "Number of milliseconds between the unix epoch and when this download began.", + "type": "string" + }, + "endTime": { + "description": "Number of milliseconds between the unix epoch and when this download ended.", + "optional": true, + "type": "string" + }, + "estimatedEndTime": { + "type": "string", + "optional": true + }, + "state": { + "$ref": "State", + "description": "Indicates whether the download is progressing, interrupted, or complete." + }, + "paused": { + "description": "True if the download has stopped reading data from the host, but kept the connection open.", + "type": "boolean" + }, + "canResume": { + "type": "boolean" + }, + "error": { + "description": "Number indicating why a download was interrupted.", + "optional": true, + "$ref": "InterruptReason" + }, + "bytesReceived": { + "description": "Number of bytes received so far from the host, without considering file compression.", + "type": "number" + }, + "totalBytes": { + "description": "Number of bytes in the whole file, without considering file compression, or -1 if unknown.", + "type": "number" + }, + "fileSize": { + "description": "Number of bytes in the whole file post-decompression, or -1 if unknown.", + "type": "number" + }, + "exists": { + "type": "boolean" + }, + "byExtensionId": { + "type": "string", + "optional": true + }, + "byExtensionName": { + "type": "string", + "optional": true + } + } + }, + { + "id": "StringDelta", + "type": "object", + "properties": { + "current": { + "optional": true, + "type": "string" + }, + "previous": { + "optional": true, + "type": "string" + } + } + }, + { + "id": "DoubleDelta", + "type": "object", + "properties": { + "current": { + "optional": true, + "type": "number" + }, + "previous": { + "optional": true, + "type": "number" + } + } + }, + { + "id": "BooleanDelta", + "type": "object", + "properties": { + "current": { + "optional": true, + "type": "boolean" + }, + "previous": { + "optional": true, + "type": "boolean" + } + } + } + ], + "functions": [ + { + "name": "download", + "type": "function", + "unsupported": true, + "description": "Download a URL. If the URL uses the HTTP[S] protocol, then the request will include all cookies currently set for its hostname. If both filename and saveAs are specified, then the Save As dialog will be displayed, pre-populated with the specified filename. If the download started successfully, callback will be called with the new DownloadItem's downloadId. If there was an error starting the download, then callback will be called with downloadId=undefined and chrome.extension.lastError will contain a descriptive string. The error strings are not guaranteed to remain backwards compatible between releases. You must not parse it.", + "parameters": [ + { + "description": "What to download and how.", + "name": "options", + "type": "object", + "properties": { + "url": { + "description": "The URL to download.", + "type": "string" + }, + "filename": { + "description": "A file path relative to the Downloads directory to contain the downloaded file.", + "optional": true, + "type": "string" + }, + "conflictAction": { + "$ref": "FilenameConflictAction", + "optional": true + }, + "saveAs": { + "description": "Use a file-chooser to allow the user to select a filename.", + "optional": true, + "type": "boolean" + }, + "method": { + "description": "The HTTP method to use if the URL uses the HTTP[S] protocol.", + "enum": [ + "GET", + "POST" + ], + "optional": true, + "type": "string" + }, + "headers": { + "optional": true, + "type": "array", + "description": "Extra HTTP headers to send with the request if the URL uses the HTTP[s] protocol. Each header is represented as a dictionary containing the keys name and either value or binaryValue, restricted to those allowed by XMLHttpRequest.", + "items": { + "type": "object", + "properties": { + "name": { + "description": "Name of the HTTP header.", + "type": "string" + }, + "value": { + "description": "Value of the HTTP header.", + "type": "string" + } + } + } + }, + "body": { + "description": "Post body.", + "optional": true, + "type": "string" + } + } + }, + { + "name": "callback", + "type": "function", + "optional": true, + "parameters": [ + { + "name": "downloadId", + "type": "integer" + } + ] + } + ] + }, + { + "name": "search", + "type": "function", + "unsupported": true, + "description": "Find DownloadItems. Set query to the empty object to get all DownloadItems. To get a specific DownloadItem, set only the id field.", + "parameters": [ + { + "name": "query", + "type": "object", + "properties": { + "query": { + "description": "This array of search terms limits results to DownloadItems whose filename or url contain all of the search terms that do not begin with a dash '-' and none of the search terms that do begin with a dash.", + "optional": true, + "type": "array", + "items": { "type": "string" } + }, + "startedBefore": { + "description": "Limits results to downloads that started before the given ms since the epoch.", + "optional": true, + "type": "string" + }, + "startedAfter": { + "description": "Limits results to downloads that started after the given ms since the epoch.", + "optional": true, + "type": "string" + }, + "endedBefore": { + "description": "Limits results to downloads that ended before the given ms since the epoch.", + "optional": true, + "type": "string" + }, + "endedAfter": { + "description": "Limits results to downloads that ended after the given ms since the epoch.", + "optional": true, + "type": "string" + }, + "totalBytesGreater": { + "description": "Limits results to downloads whose totalBytes is greater than the given integer.", + "optional": true, + "type": "number" + }, + "totalBytesLess": { + "description": "Limits results to downloads whose totalBytes is less than the given integer.", + "optional": true, + "type": "number" + }, + "filenameRegex": { + "description": "Limits results to DownloadItems whose filename matches the given regular expression.", + "optional": true, + "type": "string" + }, + "urlRegex": { + "description": "Limits results to DownloadItems whose url matches the given regular expression.", + "optional": true, + "type": "string" + }, + "limit": { + "description": "Setting this integer limits the number of results. Otherwise, all matching DownloadItems will be returned.", + "optional": true, + "type": "integer" + }, + "orderBy": { + "description": "Setting elements of this array to DownloadItem properties in order to sort the search results. For example, setting orderBy='startTime' sorts the DownloadItems by their start time in ascending order. To specify descending order, prefix orderBy with a hyphen: '-startTime'.", + "optional": true, + "type": "array", + "items": { "type": "string" } + }, + "id": { + "type": "integer", + "optional": true + }, + "url": { + "description": "Absolute URL.", + "optional": true, + "type": "string" + }, + "filename": { + "description": "Absolute local path.", + "optional": true, + "type": "string" + }, + "danger": { + "$ref": "DangerType", + "description": "Indication of whether this download is thought to be safe or known to be suspicious.", + "optional": true + }, + "mime": { + "description": "The file's MIME type.", + "optional": true, + "type": "string" + }, + "startTime": { + "optional": true, + "type": "string" + }, + "endTime": { + "optional": true, + "type": "string" + }, + "state": { + "$ref": "State", + "description": "Indicates whether the download is progressing, interrupted, or complete.", + "optional": true + }, + "paused": { + "description": "True if the download has stopped reading data from the host, but kept the connection open.", + "optional": true, + "type": "boolean" + }, + "error": { + "description": "Why a download was interrupted.", + "optional": true, + "$ref": "InterruptReason" + }, + "bytesReceived": { + "description": "Number of bytes received so far from the host, without considering file compression.", + "optional": true, + "type": "number" + }, + "totalBytes": { + "description": "Number of bytes in the whole file, without considering file compression, or -1 if unknown.", + "optional": true, + "type": "number" + }, + "fileSize": { + "description": "Number of bytes in the whole file post-decompression, or -1 if unknown.", + "optional": true, + "type": "number" + }, + "exists": { + "type": "boolean", + "optional": true + } + } + }, + { + "name": "callback", + "type": "function", + "parameters": [ + { + "items": { + "$ref": "DownloadItem" + }, + "name": "results", + "type": "array" + } + ] + } + ] + }, + { + "name": "pause", + "type": "function", + "unsupported": true, + "description": "Pause the download. If the request was successful the download is in a paused state. Otherwise chrome.extension.lastError contains an error message. The request will fail if the download is not active.", + "parameters": [ + { + "description": "The id of the download to pause.", + "name": "downloadId", + "type": "integer" + }, + { + "name": "callback", + "optional": true, + "parameters": [], + "type": "function" + } + ] + }, + { + "name": "resume", + "type": "function", + "unsupported": true, + "description": "Resume a paused download. If the request was successful the download is in progress and unpaused. Otherwise chrome.extension.lastError contains an error message. The request will fail if the download is not active.", + "parameters": [ + { + "description": "The id of the download to resume.", + "name": "downloadId", + "type": "integer" + }, + { + "name": "callback", + "optional": true, + "parameters": [], + "type": "function" + } + ] + }, + { + "name": "cancel", + "type": "function", + "unsupported": true, + "description": "Cancel a download. When callback is run, the download is cancelled, completed, interrupted or doesn't exist anymore.", + "parameters": [ + { + "description": "The id of the download to cancel.", + "name": "downloadId", + "type": "integer" + }, + { + "name": "callback", + "optional": true, + "parameters": [], + "type": "function" + } + ] + }, + { + "name": "getFileIcon", + "type": "function", + "unsupported": true, + "description": "Retrieve an icon for the specified download. For new downloads, file icons are available after the onCreated event has been received. The image returned by this function while a download is in progress may be different from the image returned after the download is complete. Icon retrieval is done by querying the underlying operating system or toolkit depending on the platform. The icon that is returned will therefore depend on a number of factors including state of the download, platform, registered file types and visual theme. If a file icon cannot be determined, chrome.extension.lastError will contain an error message.", + "parameters": [ + { + "description": "The identifier for the download.", + "name": "downloadId", + "type": "integer" + }, + { + "name": "options", + "optional": true, + "properties": { + "size": { + "description": "The size of the icon. The returned icon will be square with dimensions size * size pixels. The default size for the icon is 32x32 pixels.", + "optional": true, + "type": "integer" + } + }, + "type": "object" + }, + { + "name": "callback", + "parameters": [ + { + "name": "iconURL", + "optional": true, + "type": "string" + } + ], + "type": "function" + } + ] + }, + { + "name": "open", + "type": "function", + "unsupported": true, + "description": "Open the downloaded file.", + "parameters": [ + { + "name": "downloadId", + "type": "integer" + } + ] + }, + { + "name": "show", + "type": "function", + "unsupported": true, + "description": "Show the downloaded file in its folder in a file manager.", + "parameters": [ + { + "name": "downloadId", + "type": "integer" + } + ] + }, + { + "name": "showDefaultFolder", + "type": "function", + "unsupported": true, + "parameters": [] + }, + { + "name": "erase", + "type": "function", + "unsupported": true, + "description": "Erase matching DownloadItems from history", + "parameters": [ + { + "name": "query", + "type": "object", + "properties": { + "TODO": { + "type": "string", + "description": "complete me..." + } + } + }, + { + "name": "callback", + "type": "function", + "optional": true, + "parameters": [ + { + "items": { + "type": "integer" + }, + "name": "erasedIds", + "type": "array" + } + ] + } + ] + }, + { + "name": "removeFile", + "type": "function", + "unsupported": true, + "parameters": [ + { + "name": "downloadId", + "type": "integer" + }, + { + "name": "callback", + "type": "function", + "optional": true, + "parameters": [ ] + } + ] + }, + { + "description": "Prompt the user to either accept or cancel a dangerous download. acceptDanger() does not automatically accept dangerous downloads.", + "name": "acceptDanger", + "unsupported": true, + "parameters": [ + { + "name": "downloadId", + "type": "integer" + }, + { + "name": "callback", + "type": "function", + "optional": true, + "parameters": [ ] + } + ], + "type": "function" + }, + { + "description": "Initiate dragging the file to another application.", + "name": "drag", + "unsupported": true, + "parameters": [ + { + "name": "downloadId", + "type": "integer" + } + ], + "type": "function" + }, + { + "name": "setShelfEnabled", + "type": "function", + "unsupported": true, + "parameters": [ + { + "name": "enabled", + "type": "boolean" + } + ] + } + ], + "events": [ + { + "description": "This event fires with the DownloadItem object when a download begins.", + "name": "onCreated", + "unsupported": true, + "parameters": [ + { + "$ref": "DownloadItem", + "name": "downloadItem" + } + ], + "type": "function" + }, + { + "description": "Fires with the downloadId when a download is erased from history.", + "name": "onErased", + "unsupported": true, + "parameters": [ + { + "name": "downloadId", + "description": "The id of the DownloadItem that was erased.", + "type": "integer" + } + ], + "type": "function" + }, + { + "name": "onChanged", + "description": "When any of a DownloadItem's properties except bytesReceived changes, this event fires with the downloadId and an object containing the properties that changed.", + "unsupported": true, + "parameters": [ + { + "name": "downloadDelta", + "type": "object", + "properties": { + "id": { + "description": "The id of the DownloadItem that changed.", + "type": "integer" + }, + "url": { + "description": "Describes a change in a DownloadItem's url.", + "optional": true, + "$ref": "StringDelta" + }, + "filename": { + "description": "Describes a change in a DownloadItem's filename.", + "optional": true, + "$ref": "StringDelta" + }, + "danger": { + "description": "Describes a change in a DownloadItem's danger.", + "optional": true, + "$ref": "StringDelta" + }, + "mime": { + "description": "Describes a change in a DownloadItem's mime.", + "optional": true, + "$ref": "StringDelta" + }, + "startTime": { + "description": "Describes a change in a DownloadItem's startTime.", + "optional": true, + "$ref": "StringDelta" + }, + "endTime": { + "description": "Describes a change in a DownloadItem's endTime.", + "optional": true, + "$ref": "StringDelta" + }, + "state": { + "description": "Describes a change in a DownloadItem's state.", + "optional": true, + "$ref": "StringDelta" + }, + "canResume": { + "optional": true, + "$ref": "BooleanDelta" + }, + "paused": { + "description": "Describes a change in a DownloadItem's paused.", + "optional": true, + "$ref": "BooleanDelta" + }, + "error": { + "description": "Describes a change in a DownloadItem's error.", + "optional": true, + "$ref": "StringDelta" + }, + "totalBytes": { + "description": "Describes a change in a DownloadItem's totalBytes.", + "optional": true, + "$ref": "DoubleDelta" + }, + "fileSize": { + "description": "Describes a change in a DownloadItem's fileSize.", + "optional": true, + "$ref": "DoubleDelta" + }, + "exists": { + "optional": true, + "$ref": "BooleanDelta" + } + } + } + ], + "type": "function" + } + ] + } +] diff --git a/toolkit/components/extensions/schemas/jar.mn b/toolkit/components/extensions/schemas/jar.mn index 186efc4c4f6a..feeec5c28a32 100644 --- a/toolkit/components/extensions/schemas/jar.mn +++ b/toolkit/components/extensions/schemas/jar.mn @@ -5,6 +5,7 @@ toolkit.jar: % content extensions %content/extensions/ content/extensions/schemas/cookies.json + content/extensions/schemas/downloads.json content/extensions/schemas/extension.json content/extensions/schemas/extension_types.json content/extensions/schemas/i18n.json diff --git a/toolkit/components/extensions/test/mochitest/mochitest.ini b/toolkit/components/extensions/test/mochitest/mochitest.ini index 7bbd9fa5ffba..70acc7489294 100644 --- a/toolkit/components/extensions/test/mochitest/mochitest.ini +++ b/toolkit/components/extensions/test/mochitest/mochitest.ini @@ -30,6 +30,7 @@ support-files = skip-if = buildapp == 'b2g' # runat != document_idle is not supported. [test_ext_contentscript_create_iframe.html] [test_ext_contentscript_api_injection.html] +[test_ext_downloads.html] [test_ext_i18n_css.html] [test_ext_generate.html] [test_ext_localStorage.html] diff --git a/toolkit/components/extensions/test/mochitest/test_ext_downloads.html b/toolkit/components/extensions/test/mochitest/test_ext_downloads.html new file mode 100644 index 000000000000..f07da68c5500 --- /dev/null +++ b/toolkit/components/extensions/test/mochitest/test_ext_downloads.html @@ -0,0 +1,48 @@ + + + + WebExtension test + + + + + + + + + + + +