cloudFile

The cloudFile (a.k.a. fileLink) API first appeared in Thunderbird 64, and was uplifted to Thunderbird 60.4 ESR.

From Thunderbird 68.2.1 (Thunderbird 71 beta), an extension can choose to receive data for upload as a File object rather than as an ArrayBuffer. You should specify which you want as the default may change in a future version.

The DropBox Uploader sample extension uses this API.

Manifest file properties

[cloud_file]

(object)

management_url

(string)

A page for configuring accounts, to be displayed in the preferences UI. Note: Within this UI only a limited subset of the WebExtension APIs is available: cloudFile, extension, i18n, runtime, storage, test.

name

(string)

Name of the cloud file service.

[browser_style]

(boolean)

– [Added in TB 90]

Enable browser styles. See the MDN documentation for more information.

[data_format]

(string)

– [Added in TB 71, backported to TB 68.2.1]

Determines the format of the data argument in onFileUpload. Support for ArrayBuffer will be removed in Thunderbird 102.

Supported values:

ArrayBuffer

File

[new_account_url]

(string) Deprecated.

This property was never used.

[service_url]

(string)

URL to the web page of the cloud file service.

Note

A manifest entry named cloud_file is required to use cloudFile.

Functions

getAccount(accountId)

Retrieve information about a single cloud file account.

Parameters

accountId

(string)

Unique identifier of the account.

Return type (Promise)

getAllAccounts()

Retrieve all cloud file accounts for the current add-on.

Return type (Promise)

array of CloudFileAccount

updateAccount(accountId, updateProperties)

Update a cloud file account.

Parameters

accountId

(string)

Unique identifier of the account.

updateProperties

(object)

[configured]

(boolean)

If true, the account is configured and ready to use. Only configured accounts are offered to the user.

[managementUrl]

(string)

A page for configuring accounts, to be displayed in the preferences UI.

[spaceRemaining]

(integer)

The amount of remaining space on the cloud provider, in bytes. Set to -1 if unsupported.

[spaceUsed]

(integer)

The amount of space already used on the cloud provider, in bytes. Set to -1 if unsupported.

[uploadSizeLimit]

(integer)

The maximum size in bytes for a single file to upload. Set to -1 if unlimited.

Return type (Promise)

Events

onFileUpload

Fired when a file should be uploaded to the cloud file provider.

Parameters for onFileUpload.addListener(listener)

listener(account, fileInfo, tab)

A function that will be called when this event occurs.

Parameters passed to the listener function

account

The account used for the file upload.

fileInfo

The file to upload.

tab

(Tab)

– [Added in TB 91]

The tab where the upload was initiated. Currently only available for the message composer.

Expected return value of the listener function

object

[aborted]

(boolean)

Set this to true if the file upload was aborted.

[error]

(boolean or string)

– [Added in TB 96]

Report an error to the user. Set it to true for showing a generic error message, or set it to a specific error message.

[templateInfo]

– [Added in TB 96, backported to TB 91.4.1]

Information to override the default values used in the cloud file message template.

[url]

(string)

The URL where the uploaded file can be accessed.

onFileUploadAbort

Parameters for onFileUploadAbort.addListener(listener)

listener(account, fileId, tab)

A function that will be called when this event occurs.

Parameters passed to the listener function

account

The account used for the file upload.

fileId

(integer)

An identifier for this file.

tab

(Tab)

– [Added in TB 91]

The tab where the upload was initiated. Currently only available for the message composer.

onFileRename

– [Added in TB 96, backported to TB 91.4.1]

Fired when an already uploaded file should be renamed.

Parameters for onFileRename.addListener(listener)

listener(account, fileId, newName, tab)

A function that will be called when this event occurs.

Parameters passed to the listener function

account

The account used for the file upload.

fileId

(integer)

An identifier for the file which should be renamed.

newName

(string)

The new name of the file.

tab

(Tab)

The tab where the rename was initiated. Currently only available for the message composer.

Expected return value of the listener function

object

[error]

(boolean or string)

Report an error to the user. Set it to true for showing a generic error message, or set it to a specific error message.

[url]

(string)

The URL where the renamed file can be accessed.

onFileDeleted

Fired when a file previously uploaded should be deleted.

Parameters for onFileDeleted.addListener(listener)

listener(account, fileId, tab)

A function that will be called when this event occurs.

Parameters passed to the listener function

account

The account used for the file upload.

fileId

(integer)

An identifier for this file.

tab

(Tab)

– [Added in TB 91]

The tab where the upload was initiated. Currently only available for the message composer.

onAccountAdded

Fired when a cloud file account of this add-on was created.

Parameters for onAccountAdded.addListener(listener)

listener(account)

A function that will be called when this event occurs.

Parameters passed to the listener function

account

The created account.

onAccountDeleted

Fired when a cloud file account of this add-on was deleted.

Parameters for onAccountDeleted.addListener(listener)

listener(accountId)

A function that will be called when this event occurs.

Parameters passed to the listener function

accountId

(string)

The id of the removed account.

Types

CloudFile

Information about a cloud file.

object

data

id

(integer)

An identifier for this file.

name

(string)

Filename of the file to be transferred.

CloudFileAccount

Information about a cloud file account.

object

configured

(boolean)

If true, the account is configured and ready to use. Only configured accounts are offered to the user.

id

(string)

Unique identifier of the account.

managementUrl

(string)

A page for configuring accounts, to be displayed in the preferences UI.

name

(string)

A user-friendly name for this account.

[spaceRemaining]

(integer)

The amount of remaining space on the cloud provider, in bytes. Set to -1 if unsupported.

[spaceUsed]

(integer)

The amount of space already used on the cloud provider, in bytes. Set to -1 if unsupported.

[uploadSizeLimit]

(integer)

The maximum size in bytes for a single file to upload. Set to -1 if unlimited.

CloudFileTemplateInfo

Information to be used in the cloud file message template.

object

[service_icon]

(string)

A URL pointing to an icon to represent the used cloud file service. Defaults to the icon of the provider add-on.

[service_name]

(string)

A name to represent the used cloud file service. Defaults to the associated cloud file account name.

[service_url]

(string)

An URL to the web page of the used cloud file service, attached the service_name. Defaults to the service_url manifest entry. Set to an empty string in order to not create a link.