You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files.
WARNING: This is the BETA documentation. It may not work with the stable release of Chrome.
WARNING: This is unofficial documentation. It may not work with the current release of Chrome.

Google Chrome Extensions (Labs)

chrome.experimental.downloads

For information on how to use experimental APIs, see the chrome.experimental.* APIs page.

The downloads API allows you to programmatically initiate downloads. In the future, you will also be able to monitor and manipulate downloads.

Manifest

The downloads API is currently experimental, so you must declare the "experimental" permission to use it. Also, you must specify the hostname of any URLs to be downloaded. For example:

{
  "name": "Download Selected Links",
  "description": "Select links on a page and download them.",
  "version": "0.1",
  "permissions": [
    "experimental", "http://*/*", "https://*/*"
  ]
}

If the URL’s hostname is not specified in the permissions, then the chrome.extensions.lastError object will indicate that the extension does not have permission to access that hostname. downloads.ERROR_* are some of the errors that may be returned.

Examples

You can find simple examples of using the downloads module in the examples/api/downloads directory. For other examples and for help in viewing the source code, see Samples.

API reference: chrome.experimental.downloads

Properties

DANGER_UNCOMMON

chrome.experimental.downloads.DANGER_UNCOMMON
DANGER_UNCOMMON
( "uncommon" )
The download is not commonly downloaded and could be dangerous.

ERROR_GENERIC

chrome.experimental.downloads.ERROR_GENERIC
ERROR_GENERIC
( "I'm afraid I can't do that." )
Generic error.

ERROR_INVALID_URL

chrome.experimental.downloads.ERROR_INVALID_URL
ERROR_INVALID_URL
( "Invalid URL." )
The URL was invalid.

Methods

download

chrome.experimental.downloads.download(object options, function callback)

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 downloadId. If there was an error starting the download, then callback will be called with downloadId=undefined and chrome.extension.lastError will be set. If both filename and saveAs are specified, then the Save As dialog will be displayed, pre-populated with the specified filename.

Parameters

options
( object )
Undocumented.
url
( string )
The URL to download.
filename
( optional string )
A file path relative to the Downloads directory to contain the downloaded file.
saveAs
( optional boolean )
Use a file-chooser to allow the user to select a filename.
method
( optional enumerated string ["GET", "POST"] )
The HTTP method to use if the URL uses the HTTP[S] protocol.
headers
( optional HttpHeaders )
Extra HTTP headers to send with the request if the URL uses the HTTP[s] protocol, restricted to those allowed by XMLHttpRequest.
body
( optional string )
post body
callback
( optional function )
Undocumented.

Callback function

If you specify the callback parameter, it should specify a function that looks like this: 

function(integer downloadId) {...};
downloadId
( integer )
If not null, the identifier of the resulting Download Item.

Types

HttpHeaders

( array of object )
An array of HTTP headers. Each header is represented as a dictionary containing the keys name and either value or binaryValue.
name
( string )
Name of the HTTP header.
value
( optional string )
Value of the HTTP header if it can be represented by UTF-8.
binaryValue
( optional array of integer )
Value of the HTTP header if it cannot be represented by UTF-8, stored as individual byte values (0..255).

DownloadDangerType

( enumerated string ["safe", "file", "url", "content", "uncommon"] )
String indicating whether a download is known to be safe or is considered dangerous. The values correspond to the DANGER_SAFE, DANGER_FILE, DANGER_URL, DANGER_CONTENT, and DANGER_UNCOMMON properties.