experimental.downloads extension api docs

chrome/common/extensions/api/experimental.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": "experimental.downloads",
-    "nodoc": "true",
     "events": [
       {
         "name": "onCreated",
         "type": "function",
+        "nodoc": "true",
         "description": "This event fires with the DownloadItem object when a download begins.",
         "parameters": [
           {"name": "downloadItem", "$ref": "DownloadItem"}
         ]
       },
       {
         "name": "onChanged",
         "type": "function",
-        "description": "When any of a DownloadItem's properties except |bytesReceived| changes, this event fires with the download id and an object containing the properties that changed.",
+        "nodoc": "true",
+        "description": "When any of a DownloadItem's properties except <code>bytesReceived</code> changes, this event fires with the download id and an object containing the properties that changed.",
         "parameters": [
           {"name": "downloadDelta", "$ref": "DownloadDelta"}
         ]
       },
       {
         "name": "onErased",
         "type": "function",
+        "nodoc": "true",
         "description": "Fires with the download id when a download is erased from history.",
         "parameters": [
           {"type": "integer", "name": "downloadId"}
         ]
       }
     ],
     "properties": {
       "STATE_IN_PROGRESS": {
         "type": "string",
+        "nodoc": "true",
         "value": "in_progress",
         "description": "The download is currently receiving data from the server."
       },
       "STATE_INTERRUPTED": {
         "type": "string",
+        "nodoc": "true",
         "value": "interrupted",
         "description": "An error broke the connection with the file host."
       },
       "STATE_COMPLETE": {
         "type": "string",
+        "nodoc": "true",
         "value": "complete",
         "description": "The download has completed."
       },
       "DANGER_SAFE": {
         "type": "string",
+        "nodoc": "true",
         "value": "safe",
         "description": "The file has been determined to present no known danger to the user's computer."
       },
       "DANGER_FILE": {
         "type": "string",
+        "nodoc": "true",
         "value": "file",
         "description": "The download's filename is suspicious."
       },
       "DANGER_URL": {
         "type": "string",
+        "nodoc": "true",
         "value": "url",
         "description": "The download's URL is malicious."
       },
       "DANGER_CONTENT": {
         "type": "string",
+        "nodoc": "true",
         "value": "content",
         "description": "The download's content is malicious."
       },
       "ERROR_GENERIC": {
         "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",
+        "nodoc": "true",
         "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."
       }
     },
     "types": [
       {
         "id": "HttpHeaders",
         "type": "array",
         "description": "An array of HTTP headers. Each header is represented as a dictionary containing the keys <code>name</code> and either <code>value</code> or <code>binaryValue</code>.",
         "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"}
             }
           }
         }
       },
       {
         "id": "DownloadItem",
         "type": "object",
+        "nodoc": "true",
         "description": "The state of a file as it is downloaded from the internet.",
         "properties": {
           "id": {
             "type": "integer",
             "description": "An identifier that is persistent across browser sessions."
           },
           "url": {
             "type": "string",
             "description": "absolute URL"
           },
@@ skipping 47 matching lines @@
             "type": "integer",
             "description": "Number of bytes in the whole file, without considering file compression, or -1 if unknown."
           },
           "fileSize": {
             "type": "integer",
             "description": "Number of bytes in the whole file post-decompression, or -1 if unknown."
           }
         }
       },
       {
-        "id": "DownloadOptions",
-        "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": {
-            "$ref": "HttpHeaders",
-            "description": "Extra HTTP headers to send with the request if the URL uses the HTTP[s] protocol, restricted to those allowed by XMLHttpRequest.",
-            "optional": true
-          },
-          "body": {
-            "type": "string",
-            "description": "post body",
-            "optional": true
-          }
-        }
-      },
-      {
         "id": "DownloadQuery",
         "type": "object",
+        "nodoc": "true",
         "description": "",
         "properties": {
           "query": {
             "type": "string",
             "description": "This space-separated string of search terms that may be grouped using quotation marks limits results to downloads 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
           },
           "startedBefore": {
             "type": "integer",
             "description": "Limits results to downloads that started before the given ms since the epoch.",
@@ skipping 35 matching lines @@
             "optional": true
           },
           "limit": {
             "type": "integer",
             "optional": true,
             "description": "Setting this integer limits the number of results. Otherwise, all matching DownloadItems will be returned."
           },
           "orderBy": {
             "type": "string",
             "optional": true,
-            "description": "Setting this string to a DownloadItem property sorts the DownloadItems prior to applying the above filters. 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”."
+            "description": "Setting this string to a DownloadItem property sorts the DownloadItems prior to applying the above filters. For example, setting <code>orderBy=”startTime”</code> sorts the DownloadItems by their start time in ascending order. To specify descending order, prefix <code>orderBy</code> with a hyphen: “-startTime”."
           },
           "id": {
             "type": "integer",
             "optional": true,
             "description": "An identifier that is persistent across browser sessions."
           },
           "url": {
             "type": "string",
             "optional": true,
             "description": "absolute URL"
@@ skipping 58 matching lines @@
           "fileSize": {
             "type": "integer",
             "optional": true,
             "description": "Number of bytes in the whole file post-decompression, or -1 if unknown."
           }
         }
       },
       {
         "id": "DownloadBooleanDiff",
         "type": "object",
+        "nodoc": "true",
         "description": "Encapsulates a change in a boolean DownloadItem field.",
         "properties": {
           "old": {
             "type": "boolean",
             "optional": true
           },
           "new": {
             "type": "boolean",
             "optional": true
           }
         }
       },
       {
         "id": "DownloadIntegerDiff",
         "type": "object",
+        "nodoc": "true",
         "description": "Encapsulates a change in an integer DownloadItem field.",
         "properties": {
           "old": {
             "type": "integer",
             "optional": true
           },
           "new": {
             "type": "integer",
             "optional": true
           }
         }
       },
       {
         "id": "DownloadStringDiff",
         "type": "object",
+        "nodoc": "true",
         "description": "Encapsulates a change in a string DownloadItem field.",
         "properties": {
           "old": {
             "type": "string",
             "optional": true
           },
           "new": {
             "type": "string",
             "optional": true
           }
         }
       },
       {
         "id": "DownloadDelta",
         "type": "object",
+        "nodoc": "true",
         "description": "Encapsulates a change in a DownloadItem.",
         "properties": {
           "id": {
             "type": "integer",
             "description": "An identifier that is persistent across browser sessions."
           },
           "url": {
             "$ref": "DownloadStringDiff",
             "optional": true
           },
@@ skipping 39 matching lines @@
           },
           "totalBytes": {
             "$ref": "DownloadIntegerDiff",
             "optional": true
           },
           "fileSize": {
             "$ref": "DownloadIntegerDiff",
             "optional": true
           }
         }
-      },
-      {
-        "id": "DownloadFileIconOptions",
-        "type": "object",
-        "description": "Options for fetching the file icon for a download. See chrome.experimental.downloads.getFileIcon.",
-        "properties": {
-          "size": {
-            "type": "integer",
-            "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.",
-            "enum": [16, 32],
-            "optional": true
-          }
-        }
       }
     ],
     "functions": [
       {
         "name": "download",
         "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.",
+        "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, <code>callback</code> will be called with the new DownloadItem’s <code>downloadId</code>. If there was an error starting the download, then <code>callback</code> will be called with <code>downloadId=undefined</code> and <code>chrome.extension.lastError</code> will be set. If both <code>filename</code> and <code>saveAs</code> are specified, then the Save As dialog will be displayed, pre-populated with the specified <code>filename</code>.",
         "parameters": [
-          {"name": "options", "$ref": "DownloadOptions"},
           {
+            "type": "object",
+            "name": "options",
+            "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": {
+                "$ref": "HttpHeaders",
+                "description": "Extra HTTP headers to send with the request if the URL uses the HTTP[s] protocol, restricted to those allowed by XMLHttpRequest.",
+                "optional": true
+              },
+              "body": {
+                "type": "string",
+                "description": "post body",
+                "optional": true
+              }
+            }
+          },
+          {
+            "type": "function",
             "name": "callback",
-            "type": "function",
             "optional": true,
             "parameters": [
-              {"name": "id", "type": "integer"}
+              {
+                "name": "downloadId",
+                "type": "integer",
+                "description": "If not null, the identifier of the resulting Download Item."
+              }
             ]
           }
         ]
       },
       {
         "name": "search",
         "type": "function",
-        "description": "Find DownloadItems. Set |query| to the empty object to get all DownloadItems. To get a specific DownloadItem, set only the |id| field.",
+        "nodoc": "true",
+        "description": "Find DownloadItems. Set <code>query</code> to the empty object to get all DownloadItems. To get a specific DownloadItem, set only the <code>id</code> field.",
         "parameters": [
           {"name": "query", "$ref": "DownloadQuery"},
           {
             "name": "callback",
             "type": "function",
             "optional": true,
             "parameters": [
               {"name": "items", "type": "array"}
             ]
           }
         ]
       },
       {
         "name": "erase",
         "type": "function",
+        "nodoc": "true",
         "description": "Erase matching DownloadItems from history",
         "parameters": [
           {"name": "query", "$ref": "DownloadQuery"},
           {
             "name": "callback",
             "type": "function",
             "optional": true,
             "parameters": [
-              {"name": "ids", "type": "array"}
+              {
+                "name": "ids",
+                "type": "array",
+                "description": "The identifiers of the downloads that were erased."
+              }
             ]
           }
         ]
       },
       {
         "name": "setDestination",
         "type": "function",
-        "description": "Move the file to Downloads/relativePath instead of the Downloads directory if it has completed and pass true to callback. If |relativePath| specifies a directory that does not exist then it will be created. If it has not completed, store |relativePath| such that the file will be moved there when it completes and pass true to callback without waiting for the download to complete. Does nothing if the download is cancelled or if |downloadId| does not reference an existing DownloadItem, but pass false to callback. If the file could not be moved, then the DownloadItem will transition to STATE_INTERRUPTED, its |error| property will be set accordingly, false will be passed to callback, and the OnChanged event will fire.",
+        "nodoc": "true",
+        "description": "Move the file to Downloads/relativePath instead of the Downloads directory if it has completed and pass true to callback. If <code>relativePath</code> specifies a directory that does not exist then it will be created. If it has not completed, store <code>relativePath</code> such that the file will be moved there when it completes and pass true to callback without waiting for the download to complete. Does nothing if the download is cancelled or if <code>downloadId</code> does not reference an existing DownloadItem, but pass false to callback. If the file could not be moved, then the DownloadItem will transition to STATE_INTERRUPTED, its <code>error</code> property will be set accordingly, false will be passed to callback, and the OnChanged event will fire.",
         "parameters": [
           {"name": "id", "type": "integer"},
           {"name": "relativePath", "type": "string"}
         ]
       },
       {
         "name": "acceptDanger",
         "type": "function",
+        "nodoc": "true",
         "description": "Accept a dangerous download. If a download is dangerous, then it will not transition to the completed state until this function is called.",
         "parameters": [
           {"name": "id", "type": "integer"}
         ]
       },
       {
         "name": "show",
         "type": "function",
+        "nodoc": "true",
         "description": "Show the downloaded file in its folder.",
         "parameters": [
           {"name": "id", "type": "integer"}
         ]
       },
       {
         "name": "drag",
         "type": "function",
+        "nodoc": "true",
         "description": "Drag the file to another application",
         "parameters": [
           {"name": "id", "type": "integer"}
         ]
       },
       {
         "name": "pause",
         "type": "function",
+        "nodoc": "true",
         "description": "Pause the download.",
         "parameters": [
           {"name": "id", "type": "integer"},
           {
             "name": "callback",
             "type": "function",
             "optional": true,
             "parameters": [],
             "description": "Called when the pause request is completed. 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."
           }
         ]
       },
       {
         "name": "resume",
         "type": "function",
+        "nodoc": "true",
         "description": "Resume a paused download.",
         "parameters": [
           {"name": "id", "type": "integer"},
           {
             "name": "callback",
             "type": "function",
             "optional": true,
             "parameters": [],
             "description": "Called when the resume request is completed. 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."
           }
         ]
       },
       {
         "name": "cancel",
         "type": "function",
+        "nodoc": "true",
         "description": "Cancel a download.",
         "parameters": [
           {"name": "id", "type": "integer"},
           {
             "name": "callback",
             "type": "function",
             "optional": true,
             "parameters": [],
             "description": "Called when the request is completed. The download is cancelled, completed, interrupted or doesn't exist anymore."
           }
         ]
       },
       {
         "name": "getFileIcon",
         "type": "function",
+        "nodoc": "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.",
         "parameters": [
           {
+            "type": "integer",
             "name": "id",
-            "type": "integer",
             "description": "The identifier for the download."
           },
           {
+            "type": "object",
             "name": "options",
-            "$ref": "DownloadFileIconOptions",
-            "description": "Options for the returned image."
+            "properties": {
+              "size": {
+                "type": "integer",
+                "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.",
+                "enum": [16, 32],
+                "optional": true
+              }
+            }
           },
           {
             "name": "callback",
             "type": "function",
             "parameters": [
               {
                 "name": "iconURL",
                 "type": "string",
                 "description": "A URL to an image that represents the download. If a file icon cannot be determined, chrome.extension.lastError will contain an error message."
               }
             ]
           }
         ]
       }
     ]
   }
 ]