Official Website Blog Support

Adapt to Changes in Thunderbird 79-91

This document tries to cover all the internal changes that may be needed to make Experiment add-ons compatible with Thunderbird 91. If you find changes which are not yet listed on this page, you can ask for help and advice in one of our communication channels.

Changed API

nsISimpleEnumerator, nsIArray and nsIMutableArray

Most usage of nsIArray and nsIMutableArray has been replaced by standard JavaScript arrays and functions which returned a nsISimpleEnumeratorhave been changed to return a JavaScript array as well. The following APIs have been updated (links to actual patches, showing how core handled the change):

fixIterator() & iteratorutils.jsm

The function fixIterator() is no longer needed by any core code and was subsequently removed together with iteratorutils.jsm. It was mostly used in the following way:

for (let account of fixIterator(MailServices.accounts.accounts)) {
  ...
}

Since MailServices.accounts.accounts or MailServices.accounts.allIdentities return a simple array since Thunderbird 75, there is no need to pipe it through fixIterator() anymore. If your add-on is multi-version compatible and still supports Thunderbird 68 this has to be dealt with separately.\

nsILoadInfo.SEC_ALLOW_CROSS_ORIGIN_DATA_IS_NULL

Renamed in Beta 80 to SEC_ALLOW_CROSS_ORIGIN_SEC_CONTEXT_IS_NULL. This is often used as the aSecurityFlags argument in calls to Services.io.newChannelFromURI().

nsIChannel newChannelFromURI(
   in nsIURI aURI,
   in Node aLoadingNode,
   in nsIPrincipal aLoadingPrincipal,
   in nsIPrincipal aTriggeringPrincipal,
   in unsigned long aSecurityFlags,
   in nsContentPolicyType aContentPolicyType);

For example here.\

nsILoadInfo.SEC_REQUIRE_SAME_ORIGIN_DATA_INHERITS

Renamed in Beta 80 to SEC_REQUIRE_SAME_ORIGIN_INHERITS_SEC_CONTEXT.

nsIMsgCompose.SendMsg

Renamed in Beta 86 to nsIMsgCompose.sendMsg. It also returns a Promise now. More details can be found here.\

nsISocketTransportService.createTransport

Changed in Beta 87. Needs a fifth parameter to specify a nsIDNSRecord value, but can be null if not needed:

nsISocketTransport createTransport(in Array<ACString> aSocketTypes,
                                   in AUTF8String aHost,
                                   in long aPort,
                                   in nsIProxyInfo aProxyInfo,
                                   in nsIDNSRecord dnsRecord);

See here for more details.

IOUtils.jsm

The Thunderbird-specific IOUtils.jsm file was removed without a direct replacement. You need to alter your logic or copy code from the old JSM into your add-on. Bug 1678109 might be a good inspiration, as it contains the changes that were necessary for core code.

Renamed or Replaced API

nsIMsgCopyService.CopyFileMessage

Has been renamed to nsIMsgCopyService.copyFileMessage.

nsIMsgCopyService.CopyMessages

Has been renamed to nsIMsgCopyService.copyMessages.

nsIMsgCopyService.CopyFolders

Has been renamed to nsIMsgCopyService.copyFolder and no longer accepts an Array of src folders, but a single src folder.

nsIMsgCopyService.NotifyCompletion

Has been renamed to nsIMsgCopyService.notifyCompletion.

nsIMsgFolder.deleteSubFolders

Has been replaced by nsIMsgFolder.deleteSelf.

Removed API

Log4Moz

The file Log4moz.jsm has been removed in Thunderbird 85. Instead, use console:

  • console.debug()

  • console.log()

  • console.trace() - same as console.log(), but dumps a trace log additionally.

  • console.info()

  • console.warn()

  • console.error()

These basic log functions accept multiple parameters, which are all dumped to the console. For example:

console.log("function XY executed", objectX, objectY);

Alternatively,console.createInstance() allows to define a custom console logger, with a prefix and a maxLogLevel. The maxLogLevel can be used to disable/enable logging in debug or production builds or set the level based on users choice.

var gLog = console.createInstance({
    prefix: "My great Add-on",
    maxLogLevel: "Warn", // Error, Warn, Info, Trace, Log, Debug
  });

gLog.info("This will not be logged, as maxLogLevel is set to 'Warn'");

The levels Info, Trace and Log are actually identical.

nsIAbListener

Interface has been dropped in favor of an observer based approach. See

nsIMsgFolder.listFoldersWithFlags

Use nsIMsgFolder.getFoldersWithFlagsinstead.

nsIMsgFolderNotificationService.notifyItemElement()

Use the dedicated function MailServices.mfn.notifyMsgsJunkStatusChanged or MailServices.mfn.notifyFolderReindexTriggered instead.

Broken/Removed XUL Elements

<xul:grid>

The grid element does not seem to work anymore. Alternative is to use <html:table>.

Changes in commonly used Files

folderPane.js

The ftvItem object has been renamed to FtvItem in Beta 86.

MsgComposeCommands.js

GetMsgAttachmentElement()

Has been replaced bygAttachmentBucket. More information can be found here.

attachmentsCount()

Has been replaced by gAttachmentBucket.itemCount.

attachmentsSelectedCount()

Has been replaced by gAttachmentBucket.selectedCount.

chrome://messenger/content/newmailalert.xhtml

No longer supports the gAlertListener, gUserInitiated and gOrigin parameters when being opened (argument 1-3). Instead, the following parameters are are used now:

+  // arguments[0] --> The real nsIMsgFolder with new mail.
+  // arguments[1] --> The keys of new messages.
+  // arguments[2] --> The nsIObserver to receive window closed event

Low-level changes

Thunderbird is now multi-process (e10s)

Thunderbird can now separate content into different processes, which can only communicate through limited channels. This change has advantages relative to security and performance, but restricts code from freely accessing data that belongs to a different process.

In Thunderbird 91, this is primarily affecting pages belonging to an Add-on, like the background page or frames injected with an experiment. Most other parts of Thunderbird did not (yet!) change as much.

In practical terms, this means that you may need to update your experiments:

For most common scenarios, you can use the messaging system provided by the notifyTools to fix e10s related issues.

  • If you access your background page from an experiment running in the main Thunderbird process ("parent"), you need to switch to an e10s-compatible method to do so. For most common cases, you can use notifyTools.

  • If you create frames in Thunderbird's UI, these frames now need the appropriate attributes to load content in the right process. You can find an example of required changes in the E10S compatibility commit for the CustomUI experiment.

  • If you exchange raw objects between WebExtension scopes / "child" experiment code and Thunderbird / "parent" experiment code, you need to migrate to an indirect approach, usually based on explicit message passing. Depending on the complexity of your task, this can either happen through notifyTools, a custom experiment API or through custom experiment code directly using cross-process APIs (likely either message managers or actors).

  • As a consequence, if you load JavaScript modules in "child" experiment code, you will now get separate instances of the JSM: each process has its own instance, and there could be multiple child processes. If you keep using JSMs from "child" code, you may furthermore need to manually unload these separate instances on API shutdown (ExtensionAPI.onShutdown), even if you use a catch-all unloading solution like CachingFix or the WindowListener API.

PreviousUpdate for Thunderbird 91NextUpdate for Thunderbird 102

Last updated