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

downloads

Download files and read and modify the browser’s download history.

downloads.open

downloads.open

Open files downloaded to your computer.

Note

The permission downloads is required to use messenger.downloads.*.

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.

Parameters

downloadId

downloadId

(integer)

The id of the download to cancel.

Required permissions

  • downloads

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

options

(object)

What to download and how.

url

url

(string)

The URL to download.

allowHttpErrors

[allowHttpErrors]

(boolean, optional)

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

[body]

(string, optional)

Post body.

conflictAction

[conflictAction]

cookieStoreId

[cookieStoreId]

(string, optional)

The cookie store ID of the contextual identity; requires “cookies” permission.

filename

[filename]

(string, optional)

A file path relative to the Downloads directory to contain the downloaded file.

headers

[headers]

(array of object, 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 either value or binaryValue, restricted to those allowed by XMLHttpRequest.

incognito

[incognito]

(boolean, optional)

Whether to associate the download with a private browsing session.

method

[method]

(string, optional)

The HTTP method to use if the URL uses the HTTP[S] protocol.

Supported values:

GET

GET

POST

POST

saveAs

[saveAs]

(boolean, optional)

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).

Return type (Promise)

_returns

integer

Required permissions

  • downloads

drag(downloadId)

Initiate dragging the file to another application.

Parameters

downloadId

downloadId

(integer)

Required permissions

  • downloads

erase(query)

– [Added in TB 48]

Erase matching DownloadItems from history

Parameters

query

query

Return type (Promise)

_returns

array of integer

Required permissions

  • downloads

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

downloadId

(integer)

The identifier for the download.

options

[options]

(object, optional)

size

[size]

(integer, optional)

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.

Return type (Promise)

_returns

string

Required permissions

  • downloads

open(downloadId)

– [Added in TB 48]

Open the downloaded file.

Parameters

downloadId

downloadId

(integer)

Required permissions

  • downloads

  • downloads.open

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.

Parameters

downloadId

downloadId

(integer)

The id of the download to pause.

Required permissions

  • downloads

removeFile(downloadId)

– [Added in TB 48]

Parameters

downloadId

downloadId

(integer)

Required permissions

  • downloads

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.

Parameters

downloadId

downloadId

(integer)

The id of the download to resume.

Required permissions

  • downloads

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.

Parameters

query

query

Return type (Promise)

_returns

array of DownloadItem

Required permissions

  • downloads

show(downloadId)

– [Added in TB 48]

Show the downloaded file in its folder in a file manager.

Parameters

downloadId

downloadId

(integer)

Return type (Promise)

_returns

boolean

Required permissions

  • downloads

showDefaultFolder()

– [Added in TB 48]

Required permissions

  • downloads

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)

listener(downloadDelta)

A function that will be called when this event occurs.

Parameters passed to the listener function

downloadDelta

downloadDelta

(object)

id

id

(integer)

The id of the DownloadItem that changed.

canResume

[canResume]

(BooleanDelta, optional)

danger

[danger]

(StringDelta, optional)

Describes a change in a DownloadItem’s danger.

endTime

[endTime]

(StringDelta, optional)

Describes a change in a DownloadItem’s endTime.

error

[error]

(StringDelta, optional)

Describes a change in a DownloadItem’s error.

exists

[exists]

(BooleanDelta, optional)

filename

[filename]

(StringDelta, optional)

Describes a change in a DownloadItem’s filename.

fileSize

[fileSize]

(DoubleDelta, optional)

Describes a change in a DownloadItem’s fileSize.

mime

[mime]

(StringDelta, optional)

Describes a change in a DownloadItem’s mime.

paused

[paused]

(BooleanDelta, optional)

Describes a change in a DownloadItem’s paused.

startTime

[startTime]

(StringDelta, optional)

Describes a change in a DownloadItem’s startTime.

state

[state]

(StringDelta, optional)

Describes a change in a DownloadItem’s state.

totalBytes

[totalBytes]

(DoubleDelta, optional)

Describes a change in a DownloadItem’s totalBytes.

url

[url]

(StringDelta, optional)

Describes a change in a DownloadItem’s url.

Required permissions

  • downloads

onCreated

– [Added in TB 48]

This event fires with the DownloadItem object when a download begins.

Parameters for onCreated.addListener(listener)

listener(downloadItem)

listener(downloadItem)

A function that will be called when this event occurs.

Parameters passed to the listener function

downloadItem

downloadItem

Required permissions

  • downloads

onErased

– [Added in TB 48]

Fires with the downloadId when a download is erased from history.

Parameters for onErased.addListener(listener)

listener(downloadId)

listener(downloadId)

A function that will be called when this event occurs.

Parameters passed to the listener function

downloadId

downloadId

(integer)

The id of the DownloadItem that was erased.

Required permissions

  • downloads

Types

BooleanDelta

– [Added in TB 47]

object

current

[current]

(boolean, optional)

previous

[previous]

(boolean, optional)

DangerType

– [Added in TB 47]

These string constants will never change, however the set of DangerTypes may change.

string

Supported values:

accepted

accepted

content

content

The downloaded file is known to be malicious.

file

file

The download’s filename is suspicious.

host

host

safe

safe

The download presents no known danger to the user’s computer.

uncommon

uncommon

The download’s URL is not commonly downloaded and could be dangerous.

unwanted

unwanted

url

url

The download’s URL is known to be malicious.

DoubleDelta

– [Added in TB 47]

object

current

[current]

(number, optional)

previous

[previous]

(number, optional)

DownloadItem

object

bytesReceived

bytesReceived

(number)

Number of bytes received so far from the host, without considering file compression.

canResume

canResume

(boolean)

danger

danger

Indication of whether this download is thought to be safe or known to be suspicious.

Note

Always given as ‘safe’.

exists

exists

(boolean)

filename

filename

(string)

Absolute local path.

fileSize

fileSize

(number)

Number of bytes in the whole file post-decompression, or -1 if unknown.

id

id

(integer)

An identifier that is persistent across browser sessions.

incognito

incognito

(boolean)

False if this download is recorded in the history, true if it is not recorded.

paused

paused

(boolean)

True if the download has stopped reading data from the host, but kept the connection open.

startTime

startTime

(string)

Number of milliseconds between the unix epoch and when this download began.

state

state

(State)

Indicates whether the download is progressing, interrupted, or complete.

totalBytes

totalBytes

(number)

Number of bytes in the whole file, without considering file compression, or -1 if unknown.

url

url

(string)

Absolute URL.

byExtensionId

[byExtensionId]

(string, optional)

byExtensionName

[byExtensionName]

(string, optional)

cookieStoreId

[cookieStoreId]

(string, optional)

– [Added in TB 92]

The cookie store ID of the contextual identity.

endTime

[endTime]

(string, optional)

Number of milliseconds between the unix epoch and when this download ended.

error

[error]

(InterruptReason, optional)

Number indicating why a download was interrupted.

estimatedEndTime

[estimatedEndTime]

(string, optional)

– [Added in TB 57]

mime

[mime]

(string, optional)

The file’s MIME type.

referrer

[referrer]

(string, optional)

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

[bytesReceived]

(number, optional)

Number of bytes received so far from the host, without considering file compression.

cookieStoreId

[cookieStoreId]

(string, optional)

– [Added in TB 92]

The cookie store ID of the contextual identity.

danger

[danger]

(DangerType, optional)

Indication of whether this download is thought to be safe or known to be suspicious.

endedAfter

[endedAfter]

(DownloadTime, optional)

Limits results to downloads that ended after the given ms since the epoch.

Note

The parameter is ignored.

endedBefore

[endedBefore]

(DownloadTime, optional)

Limits results to downloads that ended before the given ms since the epoch.

Note

The parameter is ignored.

endTime

[endTime]

(string, optional)

error

[error]

(InterruptReason, optional)

Why a download was interrupted.

exists

[exists]

(boolean, optional)

filename

[filename]

(string, optional)

Absolute local path.

filenameRegex

[filenameRegex]

(string, optional)

Limits results to DownloadItems whose filename matches the given regular expression.

fileSize

[fileSize]

(number, optional)

Number of bytes in the whole file post-decompression, or -1 if unknown.

id

[id]

(integer, optional)

limit

[limit]

(integer, optional)

Setting this integer limits the number of results. Otherwise, all matching DownloadItems will be returned.

mime

[mime]

(string, optional)

The file’s MIME type.

orderBy

[orderBy]

(array of string, optional)

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

[paused]

(boolean, optional)

True if the download has stopped reading data from the host, but kept the connection open.

query

[query]

(array of string, optional)

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

[startedAfter]

(DownloadTime, optional)

Limits results to downloads that started after the given ms since the epoch.

startedBefore

[startedBefore]

(DownloadTime, optional)

Limits results to downloads that started before the given ms since the epoch.

startTime

[startTime]

(string, optional)

state

[state]

(State, optional)

Indicates whether the download is progressing, interrupted, or complete.

totalBytes

[totalBytes]

(number, optional)

Number of bytes in the whole file, without considering file compression, or -1 if unknown.

totalBytesGreater

[totalBytesGreater]

(number, optional)

Limits results to downloads whose totalBytes is greater than the given integer.

totalBytesLess

[totalBytesLess]

(number, optional)

Limits results to downloads whose totalBytes is less than the given integer.

url

[url]

(string, optional)

Absolute URL.

urlRegex

[urlRegex]

(string, optional)

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]

string

Supported values:

overwrite

overwrite

prompt

prompt

uniquify

uniquify

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

CRASH

FILE_ACCESS_DENIED

FILE_ACCESS_DENIED

FILE_BLOCKED

FILE_BLOCKED

FILE_FAILED

FILE_FAILED

FILE_NAME_TOO_LONG

FILE_NAME_TOO_LONG

FILE_NO_SPACE

FILE_NO_SPACE

FILE_SECURITY_CHECK_FAILED

FILE_SECURITY_CHECK_FAILED

FILE_TOO_LARGE

FILE_TOO_LARGE

FILE_TOO_SHORT

FILE_TOO_SHORT

FILE_TRANSIENT_ERROR

FILE_TRANSIENT_ERROR

FILE_VIRUS_INFECTED

FILE_VIRUS_INFECTED

NETWORK_DISCONNECTED

NETWORK_DISCONNECTED

NETWORK_FAILED

NETWORK_FAILED

NETWORK_INVALID_REQUEST

NETWORK_INVALID_REQUEST

NETWORK_SERVER_DOWN

NETWORK_SERVER_DOWN

NETWORK_TIMEOUT

NETWORK_TIMEOUT

SERVER_BAD_CONTENT

SERVER_BAD_CONTENT

SERVER_CERT_PROBLEM

SERVER_CERT_PROBLEM

SERVER_FAILED

SERVER_FAILED

SERVER_FORBIDDEN

SERVER_FORBIDDEN

SERVER_NO_RANGE

SERVER_NO_RANGE

SERVER_UNAUTHORIZED

SERVER_UNAUTHORIZED

USER_CANCELED

USER_CANCELED

USER_SHUTDOWN

USER_SHUTDOWN

State

– [Added in TB 47]

These string constants will never change, however the set of States may change.

string

Supported values:

complete

complete

The download completed successfully.

in_progress

in_progress

The download is currently receiving data from the server.

interrupted

interrupted

An error broke the connection with the file host.

StringDelta

– [Added in TB 47]

object

current

[current]

(string, optional)

previous

[previous]

(string, optional)