Move chrome.downloads out of experimental to dev

chrome/common/extensions/api/downloads.json

+// Copyright (c) 2012 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+[
+  {
+    "namespace": "downloads",
+    "properties": {
+      "ERROR_GENERIC": {

[Aaron Boodman, 2012/03/20 05:33:50]

I realize what you're trying to do here, but I don't think any other APIs have
these kind of error constants. I'd rather be consistent until we have a sensible
error handling mechanism.

+        "type": "string",
+        "value": "I'm afraid I can't do that.",
+        "description": "Generic error."
+      },
+      "ERROR_INVALID_URL": {
+        "type": "string",
+        "value": "Invalid URL.",
+        "description": "The URL was invalid."
+      },
+      "ERROR_INVALID_OPERATION": {
+        "type": "string",
+        "value": "Invalid operation.",
+        "description": "The requested operation cannot be performed at this time. This maybe due to the download being in a state where the requested operation is not allowed."
+      }
+    },
+    "functions": [
+      {
+        "name": "download",

[Aaron Boodman, 2012/03/20 05:33:50]

Shouldn't there be a change to download_extension_function.h to change the
DECLARE_EXTENSION_FUNCTION macro?

+        "type": "function",
+        "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 the download started successfully, |callback| will be called with the new DownloadItem’s |id|. If there was an error starting the download, then |callback| will be called with |downloadId|=undefined and chrome.extension.lastError will be set. If the URL’s hostname is not specified in the |permissions| section of the extension’s manifest, then the |chrome.extensions.lastError| object will indicate that the extension does not have permission to access that hostname.",

[Aaron Boodman, 2012/03/20 05:33:50]

I assume cookies are sent with download requests? If so, we need to require host
permissions for this API, similar to what we do for e.g., the cookies API or
chrome.tabs.executeScript. This is an important security issue and we can't ship
without it. Sorry nobody noticed it earlier.

+        "parameters": [
+          {
+            "name": "options",
+            "type": "object",
+            "properties": {
+              "url": {
+                "type": "string",
+                "description": "The URL to download.",
+                "minLength": 1
+              },
+              "filename": {
+                "type": "string",
+                "description": "A file path relative to the Downloads directory to contain the downloaded file.",
+                "optional": true
+              },
+              "saveAs": {
+                "type": "boolean",
+                "optional": true,
+                "description": "Use a file-chooser to allow the user to select a filename."
+              },
+              "method": {
+                "type": "string",
+                "description": "The HTTP method to use if the URL uses the HTTP[S] protocol.",
+                "optional": true,
+                "enum": ["GET", "POST"]
+              },
+              "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 <code>name</code> and either <code>value</code> or <code>binaryValue</code>, restricted to those allowed by XMLHttpRequest.",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "name": {"type": "string", "description": "Name of the HTTP header."},
+                    "value": {
+                      "type": "string",
+                      "optional": true,
+                      "description": "Value of the HTTP header if it can be represented by UTF-8."
+                    },
+                    "binaryValue": {
+                      "type": "array",
+                      "optional": true,
+                      "description": "Value of the HTTP header if it cannot be represented by UTF-8, stored as individual byte values (0..255).",
+                      "items": {"type": "integer"}
+                    }
+                  }
+                }
+              },
+              "body": {
+                "type": "string",
+                "description": "post body",
+                "optional": true
+              }
+            }
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "optional": true,
+            "parameters": [
+              {"name": "id", "type": "integer"}
+            ]
+          }
+        ]
+      }
+    ]
+  }
+]