downloads API
Hint
The downloads API is inherited from Firefox, and its primary documentation is maintained by Mozilla at MDN. Thunderbird implements only the subset of functions, events, and types listed here. The MDN pages may provide further details and examples, but they may also reference features that are not supported in Thunderbird.
Permissions
The following permissions influence the behavior of the API. Depending on which permissions are requested, additional methods might be available, or certain data may be included in responses.
Hint
Request permissions only when needed. Unnecessary requests may result in rejection during ATN review.
downloads
Download files and read and modify the browser’s download history.
downloads.open
Open files downloaded to your computer.
Functions
cancel(downloadId)
– [Added in TB 48]
Cancel a download. When callback is run, the download is cancelled, completed, interrupted or doesn’t exist anymore.
Required permissions
download(options)
– [Added in TB 47]
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
options
What to download and how.
url
The URL to download.
allowHttpErrors
When this flag is set to true, then the browser will allow downloads to proceed after encountering HTTP errors such as 404 Not Found.
body
Post body.
conflictAction
cookieStoreId
The cookie store ID of the contextual identity; requires “cookies” permission.
filename
A file path relative to the Downloads directory to contain the downloaded file.
headers
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.
incognito
Whether to associate the download with a private browsing session.
method
saveAs
Use a file-chooser to allow the user to select a filename. If the option is not specified, the file chooser will be shown only if the Thunderbird “Always ask you where to save files” option is enabled (i.e. the pref browser.download.useDownloadDir is set to false).
Required permissions
drag(downloadId)
Initiate dragging the file to another application.
Required permissions
erase(query)
– [Added in TB 48]
Erase matching DownloadItems from history
Required permissions
getFileIcon(downloadId, [options])
– [Added in TB 48]
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
The identifier for the download.
options
Required permissions
open(downloadId)
– [Added in TB 48]
Open the downloaded file.
Required permissions
pause(downloadId)
– [Added in TB 48]
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.
Required permissions
removeFile(downloadId)
– [Added in TB 48]
Required permissions
resume(downloadId)
– [Added in TB 48]
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.
Required permissions
search(query)
– [Added in TB 47]
Find DownloadItems. Set query to the empty object to get all DownloadItems. To get a specific DownloadItem, set only the id field.
Required permissions
show(downloadId)
– [Added in TB 48]
Show the downloaded file in its folder in a file manager.
Required permissions
showDefaultFolder()
– [Added in TB 48]
Required permissions
Events
onChanged
– [Added in TB 47]
When any of a DownloadItem’s properties except bytesReceived changes, this event fires with the downloadId and an object containing the properties that changed.
Parameters for onChanged.addListener(listener)
listener(downloadDelta)
A function that will be called when this event occurs.
Parameters passed to the listener function
downloadDelta
id
The id of the DownloadItem that changed.
canResume
danger
Describes a change in a DownloadItem’s danger.
endTime
Describes a change in a DownloadItem’s endTime.
error
Describes a change in a DownloadItem’s error.
exists
filename
Describes a change in a DownloadItem’s filename.
fileSize
Describes a change in a DownloadItem’s fileSize.
mime
Describes a change in a DownloadItem’s mime.
paused
Describes a change in a DownloadItem’s paused.
startTime
Describes a change in a DownloadItem’s startTime.
state
Describes a change in a DownloadItem’s state.
totalBytes
Describes a change in a DownloadItem’s totalBytes.
url
Describes a change in a DownloadItem’s url.
Required permissions
onCreated
– [Added in TB 48]
This event fires with the DownloadItem object when a download begins.
Parameters for onCreated.addListener(listener)
listener(downloadItem)
A function that will be called when this event occurs.
Required permissions
onErased
– [Added in TB 48]
Fires with the downloadId when a download is erased from history.
Parameters for onErased.addListener(listener)
listener(downloadId)
A function that will be called when this event occurs.
Required permissions
Types
BooleanDelta
– [Added in TB 47]
DangerType
– [Added in TB 47]
These string constants will never change, however the set of DangerTypes may change.
string
Supported values:
accepted
content
The downloaded file is known to be malicious.
file
The download’s filename is suspicious.
host
safe
The download presents no known danger to the user’s computer.
uncommon
The download’s URL is not commonly downloaded and could be dangerous.
unwanted
url
The download’s URL is known to be malicious.
DoubleDelta
– [Added in TB 47]
DownloadItem
object
bytesReceived
Number of bytes received so far from the host, without considering file compression.
canResume
danger
Indication of whether this download is thought to be safe or known to be suspicious.
Note
Always given as ‘safe’.
exists
filename
Absolute local path.
fileSize
Number of bytes in the whole file post-decompression, or -1 if unknown.
id
An identifier that is persistent across browser sessions.
incognito
False if this download is recorded in the history, true if it is not recorded.
paused
True if the download has stopped reading data from the host, but kept the connection open.
startTime
Number of milliseconds between the unix epoch and when this download began.
state
totalBytes
Number of bytes in the whole file, without considering file compression, or -1 if unknown.
url
Absolute URL.
byExtensionId
byExtensionName
cookieStoreId
The cookie store ID of the contextual identity.
endTime
Number of milliseconds between the unix epoch and when this download ended.
error
Number indicating why a download was interrupted.
estimatedEndTime
mime
The file’s MIME type.
referrer
DownloadQuery
– [Added in TB 47]
Parameters that combine to specify a predicate that can be used to select a set of downloads. Used for example in search() and erase()
object
bytesReceived
Number of bytes received so far from the host, without considering file compression.
cookieStoreId
The cookie store ID of the contextual identity.
danger
Indication of whether this download is thought to be safe or known to be suspicious.
endedAfter
Limits results to downloads that ended after the given ms since the epoch.
Note
The parameter is ignored.
endedBefore
Limits results to downloads that ended before the given ms since the epoch.
Note
The parameter is ignored.
endTime
error
Why a download was interrupted.
exists
filename
Absolute local path.
filenameRegex
Limits results to DownloadItems whose filename matches the given regular expression.
fileSize
Number of bytes in the whole file post-decompression, or -1 if unknown.
id
limit
Setting this integer limits the number of results. Otherwise, all matching DownloadItems will be returned.
mime
The file’s MIME type.
orderBy
Setting elements of this array to DownloadItem properties in order to sort the search results. 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’.
paused
True if the download has stopped reading data from the host, but kept the connection open.
query
This array of search terms 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.
startedAfter
Limits results to downloads that started after the given ms since the epoch.
startedBefore
Limits results to downloads that started before the given ms since the epoch.
startTime
state
Indicates whether the download is progressing, interrupted, or complete.
totalBytes
Number of bytes in the whole file, without considering file compression, or -1 if unknown.
totalBytesGreater
Limits results to downloads whose totalBytes is greater than the given integer.
totalBytesLess
Limits results to downloads whose totalBytes is less than the given integer.
url
Absolute URL.
urlRegex
Limits results to DownloadItems whose url matches the given regular expression.
DownloadTime
– [Added in TB 47]
A time specified as a Date object, a number or string representing milliseconds since the epoch, or an ISO 8601 string
string
or
FilenameConflictAction
– [Added in TB 47]
InterruptReason
– [Added in TB 47]
Note
Only returns these errors: NETWORK_FAILED, FILE_FAILED, CRASH, USER_CANCELED, SERVER_BAD_CONTENT, SERVER_FORBIDDEN, SERVER_UNAUTHORIZED, and SERVER_FAILED.
string
Supported values:
CRASH
FILE_ACCESS_DENIED
FILE_BLOCKED
FILE_FAILED
FILE_NAME_TOO_LONG
FILE_NO_SPACE
FILE_SECURITY_CHECK_FAILED
FILE_TOO_LARGE
FILE_TOO_SHORT
FILE_TRANSIENT_ERROR
FILE_VIRUS_INFECTED
NETWORK_DISCONNECTED
NETWORK_FAILED
NETWORK_INVALID_REQUEST
NETWORK_SERVER_DOWN
NETWORK_TIMEOUT
SERVER_BAD_CONTENT
SERVER_CERT_PROBLEM
SERVER_FAILED
SERVER_FORBIDDEN
SERVER_NO_RANGE
SERVER_UNAUTHORIZED
USER_CANCELED
USER_SHUTDOWN
State
– [Added in TB 47]
These string constants will never change, however the set of States may change.
StringDelta
– [Added in TB 47]