chrome.downloads
Description: |
Use the chrome.downloads API to programmatically initiate,
monitor, manipulate, and search for downloads.
|
Availability: |
Since Chrome 35.
|
Permissions: |
"downloads"
|
Manifest
You must declare the "downloads"
permission in the extension manifest to use this API.
{ "name": "My extension", ... "permissions": [ "downloads" ], ... }
Examples
You can find simple examples of using the chrome.downloads
API in the examples/api/downloads
directory. For other examples and for help in viewing the source code, see Samples.
Summary
Types | |
---|---|
FilenameConflictAction | |
InterruptReason | |
DangerType | |
State | |
DownloadItem | |
StringDelta | |
DoubleDelta | |
BooleanDelta | |
Methods | |
download −
chrome.downloads.download(object options, function callback)
| |
search −
chrome.downloads.search(object query, function callback)
| |
pause −
chrome.downloads.pause(integer downloadId, function callback)
| |
resume −
chrome.downloads.resume(integer downloadId, function callback)
| |
cancel −
chrome.downloads.cancel(integer downloadId, function callback)
| |
getFileIcon −
chrome.downloads.getFileIcon(integer downloadId, object options, function callback)
| |
open −
chrome.downloads.open(integer downloadId)
| |
show −
chrome.downloads.show(integer downloadId)
| |
showDefaultFolder −
chrome.downloads.showDefaultFolder()
| |
erase −
chrome.downloads.erase(object query, function callback)
| |
removeFile −
chrome.downloads.removeFile(integer downloadId, function callback)
| |
acceptDanger −
chrome.downloads.acceptDanger(integer downloadId, function callback)
| |
setShelfEnabled −
chrome.downloads.setShelfEnabled(boolean enabled)
| |
Events | |
onCreated | |
onErased | |
onChanged | |
onDeterminingFilename |
Types
FilenameConflictAction
Enum |
---|
"uniquify" ,
"overwrite" ,
or "prompt"
|
InterruptReason
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" ,
"FILE_HASH_MISMATCH" ,
"FILE_SAME_AS_SOURCE" ,
"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" ,
"SERVER_UNREACHABLE" ,
"SERVER_CONTENT_LENGTH_MISMATCH" ,
"SERVER_CROSS_ORIGIN_REDIRECT" ,
"USER_CANCELED" ,
"USER_SHUTDOWN" ,
or "CRASH"
|
DangerType
Enum |
---|
"file" ,
"url" ,
"content" ,
"uncommon" ,
"host" ,
"unwanted" ,
"safe" ,
or "accepted"
|
State
Enum |
---|
"in_progress" ,
"interrupted" ,
or "complete"
|
DownloadItem
properties | ||
---|---|---|
integer | id |
An identifier that is persistent across browser sessions. |
string | url |
The absolute URL that this download initiated from, before any redirects. |
string | finalUrl |
Since Chrome 54. The absolute URL that this download is being made from, after all redirects. |
string | referrer |
Absolute URL. |
string | filename |
Absolute local path. |
boolean | incognito |
False if this download is recorded in the history, true if it is not recorded. |
DangerType | danger |
Indication of whether this download is thought to be safe or known to be suspicious. |
string | mime |
The file's MIME type. |
string | startTime |
The time when the download began in ISO 8601 format. May be passed directly to the Date constructor: |
string | (optional) endTime |
The time when the download ended in ISO 8601 format. May be passed directly to the Date constructor: |
string | (optional) estimatedEndTime |
Estimated time when the download will complete in ISO 8601 format. May be passed directly to the Date constructor: |
State | state |
Indicates whether the download is progressing, interrupted, or complete. |
boolean | paused |
True if the download has stopped reading data from the host, but kept the connection open. |
boolean | canResume |
True if the download is in progress and paused, or else if it is interrupted and can be resumed starting from where it was interrupted. |
InterruptReason | (optional) error |
Why the download was interrupted. Several kinds of HTTP errors may be grouped under one of the errors beginning with |
double | bytesReceived |
Number of bytes received so far from the host, without considering file compression. |
double | totalBytes |
Number of bytes in the whole file, without considering file compression, or -1 if unknown. |
double | fileSize |
Number of bytes in the whole file post-decompression, or -1 if unknown. |
boolean | exists |
Whether the downloaded file still exists. This information may be out of date because Chrome does not automatically watch for file removal. Call search() in order to trigger the check for file existence. When the existence check completes, if the file has been deleted, then an onChanged event will fire. Note that search() does not wait for the existence check to finish before returning, so results from search() may not accurately reflect the file system. Also, search() may be called as often as necessary, but will not check for file existence any more frequently than once every 10 seconds. |
string | (optional) byExtensionId |
The identifier for the extension that initiated this download if this download was initiated by an extension. Does not change once it is set. |
string | (optional) byExtensionName |
The localized name of the extension that initiated this download if this download was initiated by an extension. May change if the extension changes its name or if the user changes their locale. |
StringDelta
properties | ||
---|---|---|
string | (optional) previous | |
string | (optional) current |
DoubleDelta
properties | ||
---|---|---|
double | (optional) previous | |
double | (optional) current |
BooleanDelta
properties | ||
---|---|---|
boolean | (optional) previous | |
boolean | (optional) current |
Methods
download
chrome.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 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 runtime.lastError will contain a descriptive string. The error strings are not guaranteed to remain backwards compatible between releases. Extensions must not parse it.
Parameters | |||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
object | options |
What to download and how.
|
|||||||||||||||||||||||||||
function | (optional) callback |
Called with the id of the new DownloadItem. If you specify the callback parameter, it should be a function that looks like this: function(integer downloadId) {...};
|
search
chrome.downloads.search(object query, function callback)
Find DownloadItem. Set query
to the empty object to get all DownloadItem. To get a specific DownloadItem, set only the id
field. To page through a large number of items, set orderBy: ['-startTime']
, set limit
to the number of items per page, and set startedAfter
to the startTime
of the last item from the last page.
Parameters | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
object | query |
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
function | callback |
The callback parameter should be a function that looks like this: function(array of DownloadItem results) {...};
|
pause
chrome.downloads.pause(integer downloadId, function callback)
Pause the download. If the request was successful the download is in a paused state. Otherwise runtime.lastError contains an error message. The request will fail if the download is not active.
Parameters | ||
---|---|---|
integer | downloadId |
The id of the download to pause. |
function | (optional) callback |
Called when the pause request is completed. If you specify the callback parameter, it should be a function that looks like this: function() {...};
|
resume
chrome.downloads.resume(integer downloadId, function callback)
Resume a paused download. If the request was successful the download is in progress and unpaused. Otherwise runtime.lastError contains an error message. The request will fail if the download is not active.
Parameters | ||
---|---|---|
integer | downloadId |
The id of the download to resume. |
function | (optional) callback |
Called when the resume request is completed. If you specify the callback parameter, it should be a function that looks like this: function() {...};
|
cancel
chrome.downloads.cancel(integer downloadId, function callback)
Cancel a download. When callback
is run, the download is cancelled, completed, interrupted or doesn't exist anymore.
Parameters | ||
---|---|---|
integer | downloadId |
The id of the download to cancel. |
function | (optional) callback |
Called when the cancel request is completed. If you specify the callback parameter, it should be a function that looks like this: function() {...};
|
getFileIcon
chrome.downloads.getFileIcon(integer downloadId, object options, function callback)
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, runtime.lastError will contain an error message.
Parameters | |||||
---|---|---|---|---|---|
integer | downloadId |
The identifier for the download. |
|||
object | (optional) options |
|
|||
function | callback |
A URL to an image that represents the download. The callback parameter should be a function that looks like this: function(string iconURL) {...};
|
open
chrome.downloads.open(integer downloadId)
Open the downloaded file now if the DownloadItem is complete; otherwise returns an error through runtime.lastError. Requires the "downloads.open"
permission in addition to the "downloads"
permission. An onChanged event will fire when the item is opened for the first time.
Parameters | ||
---|---|---|
integer | downloadId |
The identifier for the downloaded file. |
show
chrome.downloads.show(integer downloadId)
Show the downloaded file in its folder in a file manager.
Parameters | ||
---|---|---|
integer | downloadId |
The identifier for the downloaded file. |
showDefaultFolder
chrome.downloads.showDefaultFolder()
Show the default Downloads folder in a file manager.
erase
chrome.downloads.erase(object query, function callback)
Erase matching DownloadItem from history without deleting the downloaded file. An onErased event will fire for each DownloadItem that matches query
, then callback
will be called.
Parameters | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
object | query |
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
function | (optional) callback |
If you specify the callback parameter, it should be a function that looks like this: function(array of integer erasedIds) {...};
|
removeFile
chrome.downloads.removeFile(integer downloadId, function callback)
Remove the downloaded file if it exists and the DownloadItem is complete; otherwise return an error through runtime.lastError.
Parameters | ||
---|---|---|
integer | downloadId | |
function | (optional) callback |
If you specify the callback parameter, it should be a function that looks like this: function() {...};
|
acceptDanger
chrome.downloads.acceptDanger(integer downloadId, function callback)
Prompt the user to accept a dangerous download. Can only be called from a visible context (tab, window, or page/browser action popup). Does not automatically accept dangerous downloads. If the download is accepted, then an onChanged event will fire, otherwise nothing will happen. When all the data is fetched into a temporary file and either the download is not dangerous or the danger has been accepted, then the temporary file is renamed to the target filename, the |state| changes to 'complete', and onChanged fires.
Parameters | ||
---|---|---|
integer | downloadId |
The identifier for the DownloadItem. |
function | (optional) callback |
Called when the danger prompt dialog closes. If you specify the callback parameter, it should be a function that looks like this: function() {...};
|
setShelfEnabled
chrome.downloads.setShelfEnabled(boolean enabled)
Enable or disable the gray shelf at the bottom of every window associated with the current browser profile. The shelf will be disabled as long as at least one extension has disabled it. Enabling the shelf while at least one other extension has disabled it will return an error through runtime.lastError. Requires the "downloads.shelf"
permission in addition to the "downloads"
permission.
Parameters | ||
---|---|---|
boolean | enabled |
Events
onCreated
This event fires with the DownloadItem object when a download begins.
addListener
chrome.downloads.onCreated.addListener(function callback)
Parameters | |||||
---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function( DownloadItem downloadItem) {...};
|
onErased
Fires with the downloadId
when a download is erased from history.
addListener
chrome.downloads.onErased.addListener(function callback)
Parameters | |||||
---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(integer downloadId) {...};
|
onChanged
When any of a DownloadItem's properties except bytesReceived
and estimatedEndTime
changes, this event fires with the downloadId
and an object containing the properties that changed.
addListener
chrome.downloads.onChanged.addListener(function callback)
Parameters | ||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(object downloadDelta) {...};
|
onDeterminingFilename
During the filename determination process, extensions will be given the opportunity to override the target DownloadItem.filename. Each extension may not register more than one listener for this event. Each listener must call suggest
exactly once, either synchronously or asynchronously. If the listener calls suggest
asynchronously, then it must return true
. If the listener neither calls suggest
synchronously nor returns true
, then suggest
will be called automatically. The DownloadItem will not complete until all listeners have called suggest
. Listeners may call suggest
without any arguments in order to allow the download to use downloadItem.filename
for its filename, or pass a suggestion
object to suggest
in order to override the target filename. If more than one extension overrides the filename, then the last extension installed whose listener passes a suggestion
object to suggest
wins. In order to avoid confusion regarding which extension will win, users should not install extensions that may conflict. If the download is initiated by download and the target filename is known before the MIME type and tentative filename have been determined, pass filename
to download instead.
addListener
chrome.downloads.onDeterminingFilename.addListener(function callback)
Parameters | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function( DownloadItem downloadItem, function suggest) {...};
|