chrome.downloads
Warning: This API is still under development. It is only available for Chrome users on the dev early release channel.
The downloads API allows you to programmatically initiate, monitor,
manipulate, and search for downloads.
Manifest
You must declare the 'downloads' permission in the extension manifest to use this API, along with host permissions for any hosts that you
may pass to download().
{
'name': 'My extension',
...
'permissions': [
'downloads',
'*://*.google.com'
],
...
}
If the URL's hostname is not specified in the permissions, then download() will call its callback with a null
downloadId and set the chrome.extensions.lastError
object to indicate that the extension does not have permission to access that
hostname.
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.downloads
Types
( object )
-
name
(
string
)
-
Name of the HTTP header.
-
value
(
string
)
-
Value of the HTTP header.
HttpMethod
( enumerated string ["GET", "POST"] )
DownloadOptions
( object )
-
body
(
optional
string
)
-
Post body.
-
saveAs
(
optional
boolean
)
-
Use a file-chooser to allow the user to select a filename.
-
url
(
string
)
-
The URL to download.
-
filename
(
optional
string
)
-
A file path relative to the Downloads directory to contain the downloaded file.
-
headers
(
optional
array of HeaderNameValuePair
)
-
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.
-
method
(
optional
HttpMethod
)
-
The HTTP method to use if the URL uses the HTTP[S] protocol.
DangerType
( enumerated string ["file", "url", "content", "uncommon", "safe"] )
- 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.
State
( enumerated string ["in_progress", "interrupted", "complete"] )
- 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.
DownloadItem
( object )
-
bytesReceived
(
integer
)
-
Number of bytes received so far from the host, without considering file compression.
-
danger
(
DangerType
)
-
Indication of whether this download is thought to be safe or known to be suspicious.
-
url
(
string
)
-
Absolute URL.
-
totalBytes
(
integer
)
-
Number of bytes in the whole file, without considering file compression, or -1 if unknown.
-
dangerAccepted
(
optional
boolean
)
-
True if the user has accepted the download's danger.
-
filename
(
string
)
-
Absolute local path.
-
paused
(
boolean
)
-
True if the download has stopped reading data from the host, but kept the connection open.
-
state
(
State
)
-
Indicates whether the download is progressing, interrupted, or complete.
-
mime
(
string
)
-
The file's MIME type.
-
fileSize
(
integer
)
-
Number of bytes in the whole file post-decompression, or -1 if unknown.
-
startTime
(
integer
)
-
Number of milliseconds between the unix epoch and when this download began.
-
error
(
optional
integer
)
-
Number indicating why a download was interrupted.
-
endTime
(
optional
integer
)
-
Number of milliseconds between the unix epoch and when this download ended.
-
id
(
integer
)
-
An identifier that is persistent across browser sessions.
-
incognito
(
boolean
)
-
False if this download is recorded in the history, true if it is not recorded.
DownloadQuery
( object )
-
orderBy
(
optional
string
)
-
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'.
-
urlRegex
(
optional
string
)
-
Limits results to DownloadItems whose
url matches the given regular expression.
-
endedBefore
(
optional
integer
)
-
Limits results to DownloadItems that ended before the given ms since the epoch.
-
totalBytesGreater
(
optional
integer
)
-
Limits results to DownloadItems whose
totalBytes is greater than the given integer.
-
danger
(
optional
DangerType
)
-
Indication of whether this download is thought to be safe or known to be suspicious.
-
totalBytes
(
optional
integer
)
-
Number of bytes in the whole file, without considering file compression, or -1 if unknown.
-
paused
(
optional
boolean
)
-
True if the download has stopped reading data from the host, but kept the connection open.
-
filenameRegex
(
optional
string
)
-
Limits results to DownloadItems whose
filename matches the given regular expression.
-
query
(
optional
string
)
-
This space-separated string of search terms that may be grouped using quotation marks 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.
-
totalBytesLess
(
optional
integer
)
-
Limits results to DownloadItems whose
totalBytes is less than the given integer.
-
id
(
optional
integer
)
-
The
id of the DownloadItem that changed.
-
bytesReceived
(
optional
integer
)
-
Number of bytes received so far from the host, without considering file compression.
-
endedAfter
(
optional
integer
)
-
Limits results to DownloadItems that ended after the given ms since the epoch.
-
filename
(
optional
string
)
-
Absolute local path.
-
state
(
optional
State
)
-
Indicates whether the download is progressing, interrupted, or complete.
-
startedAfter
(
optional
integer
)
-
Limits results to DownloadItems that started after the given ms since the epoch.
-
dangerAccepted
(
optional
boolean
)
-
True if the user has accepted the download's danger.
-
mime
(
optional
string
)
-
The file's MIME type.
-
fileSize
(
optional
integer
)
-
Number of bytes in the whole file post-decompression, or -1 if unknown.
-
startTime
(
optional
integer
)
-
Number of milliseconds between the unix epoch and when this download began.
-
url
(
optional
string
)
-
Absolute URL.
-
startedBefore
(
optional
integer
)
-
Limits results to DownloadItems that started before the given ms since the epoch.
-
limit
(
optional
integer
)
-
Setting this integer limits the number of results. Otherwise, all matching DownloadItems will be returned.
-
error
(
optional
integer
)
-
Number indicating why a download was interrupted.
-
endTime
(
optional
integer
)
-
Number of milliseconds between the unix epoch and when this download ended.
DownloadStringDiff
( object )
-
current
(
optional
string
)
-
previous
(
optional
string
)
DownloadLongDiff
( object )
-
current
(
optional
integer
)
-
previous
(
optional
integer
)
DownloadBooleanDiff
( object )
-
current
(
optional
boolean
)
-
previous
(
optional
boolean
)
DownloadDelta
( object )
-
id
(
integer
)
-
An identifier that is persistent across browser sessions.
GetFileIconOptions
( object )
-
size
(
optional
integer
)
-
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.
Methods
download
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
Callback function
If you specify the callback parameter, it should specify a function that looks like this:
function(integer downloadId) {...};
search
Find DownloadItems. Set query to the empty object to get all DownloadItems. To get a specific DownloadItem, set only the id field.
Parameters
Callback function
The callback parameter should specify a function that looks like this:
function(array of DownloadItem results) {...};
pause
chrome.downloads.pause(integer downloadId)
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
- downloadId ( integer )
- The id of the download to pause.
Callback function
If you specify the callback parameter, it should specify a function that looks like this:
function() {...};
resume
chrome.downloads.resume(integer downloadId)
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
- downloadId ( integer )
- The id of the download to resume.
Callback function
If you specify the callback parameter, it should specify a function that looks like this:
function() {...};
cancel
chrome.downloads.cancel(integer downloadId)
Cancel a download. When callback is run, the download is cancelled, completed, interrupted or doesn't exist anymore.
Parameters
- downloadId ( integer )
- The id of the download to cancel.
Callback function
If you specify the callback parameter, it should specify a function that looks like this:
function() {...};
getFileIcon
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
- downloadId ( integer )
- The identifier for the download.
Callback function
The callback parameter should specify a function that looks like this:
function(string iconURL) {...}; - iconURL ( optional string )
Events
onCreated
chrome.downloads.onCreated
.addListener(function(
DownloadItem downloadItem)
{...});
This event fires with the DownloadItem object when a download begins.
Listener Parameters
onErased
chrome.downloads.onErased.addListener(function(integer downloadId) {...});
Fires with the downloadId when a download is erased from history.
Listener Parameters
- downloadId ( integer )
- The
id of the DownloadItem that was erased.
onChanged
chrome.downloads.onChanged
.addListener(function(
DownloadDelta downloadDelta)
{...});
When any of a DownloadItem's properties except bytesReceived changes, this event fires with the downloadId and an object containing the properties that changed.
Listener Parameters
Sample Extensions that use chrome.downloads
Download Selected Links –
Select links on a page and download them.