chrome.downloads
- Description
Use the
chrome.downloads
API to programmatically initiate, monitor, manipulate, and search for downloads. - 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
- Methods
chrome.downloads.acceptDanger(downloadId: number, callback: function)
chrome.downloads.cancel(downloadId: number, callback: function)
chrome.downloads.download(options: DownloadOptions, callback: function)
chrome.downloads.erase(query: DownloadQuery, callback: function)
chrome.downloads.getFileIcon(downloadId: number, options?: GetFileIconOptions, callback: function)
chrome.downloads.open(downloadId: number)
chrome.downloads.pause(downloadId: number, callback: function)
chrome.downloads.removeFile(downloadId: number, callback: function)
chrome.downloads.resume(downloadId: number, callback: function)
chrome.downloads.search(query: DownloadQuery, callback: function)
chrome.downloads.setShelfEnabled(enabled: boolean)
chrome.downloads.show(downloadId: number)
chrome.downloads.showDefaultFolder()
- Events
Types
BooleanDelta
Properties
- currentboolean optional
- previousboolean optional
DoubleDelta
Properties
- currentnumber optional
- previousnumber optional
DownloadDelta
Properties
- canResumeBooleanDelta optional
The change in
canResume
, if any. - dangerStringDelta optional
The change in
danger
, if any. - endTimeStringDelta optional
The change in
endTime
, if any. - errorStringDelta optional
The change in
error
, if any. - existsBooleanDelta optional
The change in
exists
, if any. - fileSizeDoubleDelta optional
The change in
fileSize
, if any. - filenameStringDelta optional
The change in
filename
, if any. - finalUrlStringDelta optional
The change in
finalUrl
, if any. - idnumber
The
id
of theDownloadItem
that changed. - mimeStringDelta optional
The change in
mime
, if any. - pausedBooleanDelta optional
The change in
paused
, if any. - startTimeStringDelta optional
The change in
startTime
, if any. - stateStringDelta optional
The change in
state
, if any. - totalBytesDoubleDelta optional
The change in
totalBytes
, if any. - urlStringDelta optional
The change in
url
, if any.
DownloadItem
Properties
- byExtensionIdstring optional
The identifier for the extension that initiated this download if this download was initiated by an extension. Does not change once it is set.
- byExtensionNamestring optional
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.
- bytesReceivednumber
Number of bytes received so far from the host, without considering file compression.
- canResumeboolean
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.
- danger
Indication of whether this download is thought to be safe or known to be suspicious.
- endTimestring optional
The time when the download ended in ISO 8601 format. May be passed directly to the Date constructor:
chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.endTime) console.log(new Date(item.endTime))})})
- errorInterruptReason optional
Why the download was interrupted. Several kinds of HTTP errors may be grouped under one of the errors beginning with
SERVER_
. Errors relating to the network begin withNETWORK_
, errors relating to the process of writing the file to the file system begin withFILE_
, and interruptions initiated by the user begin withUSER_
. - estimatedEndTimestring optional
Estimated time when the download will complete in ISO 8601 format. May be passed directly to the Date constructor:
chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.estimatedEndTime) console.log(new Date(item.estimatedEndTime))})})
- existsboolean
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 anonChanged
event will fire. Note thatsearch
() does not wait for the existence check to finish before returning, so results fromsearch
() 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. - fileSizenumber
Number of bytes in the whole file post-decompression, or -1 if unknown.
- filenamestring
Absolute local path.
- finalUrlstring
The absolute URL that this download is being made from, after all redirects.
- idnumber
An identifier that is persistent across browser sessions.
- incognitoboolean
False if this download is recorded in the history, true if it is not recorded.
- mimestring
The file's MIME type.
- pausedboolean
True if the download has stopped reading data from the host, but kept the connection open.
- referrerstring
Absolute URL.
- startTimestring
The time when the download began in ISO 8601 format. May be passed directly to the Date constructor:
chrome.downloads.search({}, function(items){items.forEach(function(item){console.log(new Date(item.startTime))})})
- state
Indicates whether the download is progressing, interrupted, or complete.
- totalBytesnumber
Number of bytes in the whole file, without considering file compression, or -1 if unknown.
- urlstring
The absolute URL that this download initiated from, before any redirects.
DownloadOptions
Properties
- bodystring optional
Post body.
- conflictActionFilenameConflictAction optional
The action to take if
filename
already exists. - filenamestring optional
A file path relative to the Downloads directory to contain the downloaded file, possibly containing subdirectories. Absolute paths, empty paths, and paths containing back-references ".." will cause an error.
onDeterminingFilename
allows suggesting a filename after the file's MIME type and a tentative filename have been determined. - headersHeaderNameValuePair[] optional
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 eithervalue
orbinaryValue
, restricted to those allowed by XMLHttpRequest. - methodHttpMethod optional
The HTTP method to use if the URL uses the HTTP[S] protocol.
- saveAsboolean optional
Use a file-chooser to allow the user to select a filename regardless of whether
filename
is set or already exists. - urlstring
The URL to download.
DownloadQuery
Properties
- bytesReceivednumber optional
Number of bytes received so far from the host, without considering file compression.
- dangerDangerType optional
Indication of whether this download is thought to be safe or known to be suspicious.
- endTimestring optional
The time when the download ended in ISO 8601 format.
- endedAfterstring optional
Limits results to
DownloadItem
that ended after the given ms since the epoch. - endedBeforestring optional
Limits results to
DownloadItem
that ended before the given ms since the epoch. - errorInterruptReason optional
Why a download was interrupted.
- existsboolean optional
Whether the downloaded file exists;
- fileSizenumber optional
Number of bytes in the whole file post-decompression, or -1 if unknown.
- filenamestring optional
Absolute local path.
- filenameRegexstring optional
Limits results to
DownloadItem
whosefilename
matches the given regular expression. - finalUrlstring optional
The absolute URL that this download is being made from, after all redirects.
- finalUrlRegexstring optional
Limits results to
DownloadItem
whosefinalUrl
matches the given regular expression. - idnumber optional
The
id
of theDownloadItem
to query. - limitnumber optional
The maximum number of matching
DownloadItem
returned. Defaults to 1000. Set to 0 in order to return all matchingDownloadItem
. Seesearch
for how to page through results. - mimestring optional
The file's MIME type.
- orderBystring[] optional
Set elements of this array to
DownloadItem
properties in order to sort search results. For example, settingorderBy=['startTime']
sorts theDownloadItem
by their start time in ascending order. To specify descending order, prefix with a hyphen: '-startTime'. - pausedboolean optional
True if the download has stopped reading data from the host, but kept the connection open.
- querystring[] optional
This array of search terms limits results to
DownloadItem
whosefilename
orurl
orfinalUrl
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. - startTimestring optional
The time when the download began in ISO 8601 format.
- startedAfterstring optional
Limits results to
DownloadItem
that started after the given ms since the epoch. - startedBeforestring optional
Limits results to
DownloadItem
that started before the given ms since the epoch. - stateState optional
Indicates whether the download is progressing, interrupted, or complete.
- totalBytesnumber optional
Number of bytes in the whole file, without considering file compression, or -1 if unknown.
- totalBytesGreaternumber optional
Limits results to
DownloadItem
whosetotalBytes
is greater than the given integer. - totalBytesLessnumber optional
Limits results to
DownloadItem
whosetotalBytes
is less than the given integer. - urlstring optional
The absolute URL that this download initiated from, before any redirects.
- urlRegexstring optional
Limits results to
DownloadItem
whoseurl
matches the given regular expression.
FilenameSuggestion
Properties
- conflictActionFilenameConflictAction optional
The action to take if
filename
already exists. - filenamestring
The
DownloadItem
's new targetDownloadItem.filename
, as a path relative to the user's default Downloads directory, possibly containing subdirectories. Absolute paths, empty paths, and paths containing back-references ".." will be ignored.filename
is ignored if there are anyonDeterminingFilename
listeners registered by any extensions.
GetFileIconOptions
Properties
- sizenumber optional
The size of the returned icon. The icon will be square with dimensions size * size pixels. The default and largest size for the icon is 32x32 pixels. The only supported sizes are 16 and 32. It is an error to specify any other size.
HeaderNameValuePair
Properties
- namestring
Name of the HTTP header.
- valuestring
Value of the HTTP header.
StringDelta
Properties
- currentstring optional
- previousstring optional
DangerType
- 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.
- host
- The download came from a host known to distribute malicious binaries and is likely dangerous.
- unwanted
- The download is potentially unwanted or unsafe. E.g. it could make changes to browser or computer settings.
- safe
- The download presents no known danger to the user's computer.
- accepted
- The user has accepted the dangerous download.
Enum
"file"
, "url"
, "content"
, "uncommon"
, "host"
, "unwanted"
, "safe"
, or "accepted"
FilenameConflictAction
- uniquify
- To avoid duplication, the
filename
is changed to include a counter before the filename extension. - overwrite
- The existing file will be overwritten with the new file.
- prompt
- The user will be prompted with a file chooser dialog.
Enum
"uniquify"
, "overwrite"
, or "prompt"
HttpMethod
Enum
"GET"
, or "POST"
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"
State
- 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.
Enum
"in_progress"
, "interrupted"
, or "complete"
Methods
acceptDanger
chrome.downloads.acceptDanger(downloadId: number, callback: function)
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
- downloadIdnumber
The identifier for the
DownloadItem
. - callbackfunction
Called when the danger prompt dialog closes.
The callback parameter should be a function that looks like this:
() => {...}
cancel
chrome.downloads.cancel(downloadId: number, callback: function)
Cancel a download. When callback
is run, the download is cancelled, completed, interrupted or doesn't exist anymore.
Parameters
- downloadIdnumber
The id of the download to cancel.
- callbackfunction
Called when the cancel request is completed.
The callback parameter should be a function that looks like this:
() => {...}
download
chrome.downloads.download(options: DownloadOptions, callback: function)
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
- options
What to download and how.
- callbackfunction
Called with the id of the new
DownloadItem
.The callback parameter should be a function that looks like this:
(downloadId: number) => {...}
- downloadIdnumber
erase
chrome.downloads.erase(query: DownloadQuery, callback: function)
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
- query
- callbackfunction
The callback parameter should be a function that looks like this:
(erasedIds: number[]) => {...}
- erasedIdsnumber[]
getFileIcon
chrome.downloads.getFileIcon(downloadId: number, options?: GetFileIconOptions, callback: function)
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
- downloadIdnumber
The identifier for the download.
- optionsGetFileIconOptions optional
- callbackfunction
A URL to an image that represents the download.
The callback parameter should be a function that looks like this:
(iconURL: string) => {...}
- iconURLstring
open
chrome.downloads.open(downloadId: number)
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
- downloadIdnumber
The identifier for the downloaded file.
pause
chrome.downloads.pause(downloadId: number, callback: function)
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
- downloadIdnumber
The id of the download to pause.
- callbackfunction
Called when the pause request is completed.
The callback parameter should be a function that looks like this:
() => {...}
removeFile
chrome.downloads.removeFile(downloadId: number, callback: function)
Remove the downloaded file if it exists and the DownloadItem
is complete; otherwise return an error through runtime.lastError
.
Parameters
- downloadIdnumber
- callbackfunction
The callback parameter should be a function that looks like this:
() => {...}
resume
chrome.downloads.resume(downloadId: number, callback: function)
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
- downloadIdnumber
The id of the download to resume.
- callbackfunction
Called when the resume request is completed.
The callback parameter should be a function that looks like this:
() => {...}
search
chrome.downloads.search(query: DownloadQuery, callback: function)
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
- query
- callbackfunction
The callback parameter should be a function that looks like this:
(results: DownloadItem[]) => {...}
- results
setShelfEnabled
chrome.downloads.setShelfEnabled(enabled: boolean)
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
- enabledboolean
show
chrome.downloads.show(downloadId: number)
Show the downloaded file in its folder in a file manager.
Parameters
- downloadIdnumber
The identifier for the downloaded file.
showDefaultFolder
chrome.downloads.showDefaultFolder()
Show the default Downloads folder in a file manager.
Events
onChanged
chrome.downloads.onChanged.addListener(listener: function)
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.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(downloadDelta: DownloadDelta) => {...}
- downloadDelta
onCreated
chrome.downloads.onCreated.addListener(listener: function)
This event fires with the DownloadItem
object when a download begins.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(downloadItem: DownloadItem) => {...}
- downloadItem
onDeterminingFilename
chrome.downloads.onDeterminingFilename.addListener(listener: function)
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.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(downloadItem: DownloadItem, suggest: function) => {...}
- downloadItem
- suggestfunction
onErased
chrome.downloads.onErased.addListener(listener: function)
Fires with the downloadId
when a download is erased from history.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(downloadId: number) => {...}
- downloadIdnumber
The
id
of theDownloadItem
that was erased.