AddonManager Reference

class AddonManager()

This is the public API that UI and developers should be calling. All methods just forward to AddonManagerInternal.

AddonManager.addAddonListener()

Adds a new AddonListener if the listener is not already registered.

Arguments:
  • aListener (AddonManagerListener) – The AddonListener to add.
AddonManager.addInstallListener()

Adds a new InstallListener if the listener is not already registered.

Arguments:
  • aListener – The InstallListener to add
AddonManager.addManagerListener()

Adds a new AddonManagerListener if the listener is not already registered.

Arguments:
  • aListener (AddonManagerListener) – The listener to add
AddonManager.addStartupChange()

Adds a add-on to the list of detected changes for this startup. If addStartupChange is called multiple times for the same add-on in the same startup then only the most recent change will be remembered.

Arguments:
  • aType – The type of change as a string. Providers can define their own types of changes or use the existing defined STARTUP_CHANGE_* constants
  • aID – The ID of the add-on
AddonManager.addTypeListener()

Adds a new TypeListener if the listener is not already registered.

Arguments:
  • aListener (TypeListener) – The TypeListener to add
AddonManager.addUpgradeListener()

Adds new or overrides existing UpgradeListener.

Arguments:
  • aInstanceID – The instance ID of an addon to register a listener for.
  • aCallback – The callback to invoke when updates are available for this addon.
Throws:

if there is no addon matching the instanceID
AddonManager.backgroundUpdateCheck()

Performs a background update check by starting an update for all add-ons that can be updated.

Returns:null – Promise Resolves when the background update check is complete (the resulting addon installations may still be in progress).
AddonManager.callAddonListeners()

Calls all registered AddonListeners with an event. Any parameters after the method parameter are passed to the listener.

Arguments:
  • aMethod – The method on the listeners to call
AddonManager.callInstallListeners()

Calls all registered InstallListeners with an event. Any parameters after the extraListeners parameter are passed to the listener.

Arguments:
  • aMethod – The method on the listeners to call
  • aExtraListeners – An optional array of extra InstallListeners to also call
Returns:

false if any of the listeners returned false, true otherwise
AddonManager.callManagerListeners()

Calls all registered AddonManagerListeners with an event. Any parameters after the method parameter are passed to the listener.

Arguments:
  • aMethod – The method on the listeners to call
AddonManager.callProviders()

Calls a method on all registered providers if it exists and consumes any thrown exception. Return values are ignored. Any parameters after the method parameter are passed to the provider’s method. WARNING: Do not use for asynchronous calls; callProviders() does not invoke callbacks if provider methods throw synchronous exceptions.

Arguments:
  • aMethod – The method name to call
AddonManager.escapeAddonURI()

Replaces %…% strings in an addon url (update and updateInfo) with appropriate values.

Arguments:
  • aAddon – The Addon representing the add-on
  • aUri – The string representation of the URI to escape
  • aAppVersion – The optional application version to use for %APP_VERSION%
Returns:

The appropriately escaped URI.
AddonManager.getActiveAddons()

Gets active add-ons of specific types.

This is similar to getAddonsByTypes() but it may return a limited amount of information about only active addons. Consequently, it can be implemented by providers using only immediately available data as opposed to getAddonsByTypes which may require I/O).

Arguments:
  • aTypes – An optional array of types to retrieve. Each type is a string name
AddonManager.getAddonByID()

Asynchronously gets an add-on with a specific ID.

Arguments:
  • aID (string) – The ID of the add-on to retrieve
Throws:

if the aID argument is not specified
Returns:

Promise – resolves with the found Addon or null if no such add-on exists. Never rejects.
AddonManager.getAddonByInstanceID()

Returns an Addon corresponding to an instance ID.

Arguments:
  • aInstanceID – An Addon Instance ID symbol
Throws:

if the aInstanceID argument is not specified or the AddonManager is not initialized
Returns:

Promise –
AddonManager.getAddonBySyncGUID()

Asynchronously get an add-on with a specific Sync GUID.

Arguments:
  • aGUID – String GUID of add-on to retrieve
Throws:

if the aGUID argument is not specified
AddonManager.getAddonsByIDs()

Asynchronously gets an array of add-ons.

Arguments:
  • aIDs – The array of IDs to retrieve
Throws:

if the aIDs argument is not specified
Returns:

Promise –
AddonManager.getAddonsByTypes()

Asynchronously gets add-ons of specific types.

Arguments:
  • aTypes – An optional array of types to retrieve. Each type is a string name
AddonManager.getAddonsWithOperationsByTypes()

Asynchronously gets add-ons that have operations waiting for an application restart to complete.

Arguments:
  • aTypes – An optional array of types to retrieve. Each type is a string name
AddonManager.getAllAddons()

Asynchronously gets all installed add-ons.

AddonManager.getAllInstalls()

Asynchronously gets all current AddonInstalls.

AddonManager.getInstallForFile()

Asynchronously gets an AddonInstall for an nsIFile.

Arguments:
  • aFile – The nsIFile where the add-on is located
  • aMimetype – An optional mimetype hint for the add-on
Throws:

if the aFile or aCallback arguments are not specified
AddonManager.getInstallForURL()

Asynchronously gets an AddonInstall for a URL.

Arguments:
  • aUrl – The string represenation of the URL the add-on is located at
  • aMimetype – The mimetype of the add-on
  • aHash – An optional hash of the add-on
  • aName – An optional placeholder name while the add-on is being downloaded
  • aIcons – Optional placeholder icons while the add-on is being downloaded
  • aVersion – An optional placeholder version while the add-on is being downloaded
  • aBrowser – An optional <browser> element for download permissions prompts.
Throws:

if the aUrl, aCallback or aMimetype arguments are not specified
AddonManager.getInstallsByTypes()

Asynchronously gets all current AddonInstalls optionally limiting to a list of types.

Arguments:
  • aTypes – An optional array of types to retrieve. Each type is a string name
Throws:

If the aCallback argument is not specified
AddonManager.getPreferredIconURL()

Gets an icon from the icon set provided by the add-on that is closest to the specified size.

The optional window parameter will be used to determine the screen resolution and select a more appropriate icon. Calling this method with 48px on retina screens will try to match an icon of size 96px.

Arguments:
  • aAddon – An addon object, meaning: An object with either an icons property that is a key-value list of icon size and icon URL, or an object having an iconURL and icon64URL property.
  • aSize – Ideal icon size in pixels
  • aWindow – Optional window object for determining the correct scale.
Returns:

String – The absolute URL of the icon or null if the addon doesn’t have icons
AddonManager.getStartupChanges()

Gets an array of add-on IDs that changed during the most recent startup.

Arguments:
  • aType – The type of startup change to get
Returns:

An array of add-on IDs
AddonManager.init
AddonManager.installAddonFromAOM()

Starts installation of an AddonInstall created from add-ons manager front-end code (e.g., drag-and-drop of xpis or “Install Add-on from File”

Arguments:
  • browser – The browser element where the installation was initiated
  • uri – The URI of the page where the installation was initiated
  • install – The AddonInstall to be installed
AddonManager.installAddonFromWebpage()

Starts installation of an AddonInstall notifying the registered web install listener of blocked or started installs.

Arguments:
  • aMimetype – The mimetype of add-ons being installed
  • aBrowser – The optional browser element that started the installs
  • aInstallingPrincipal – The nsIPrincipal that initiated the install
  • aInstall – The AddonInstall to be installed
AddonManager.installTemporaryAddon()

Installs a temporary add-on from a local file or directory.

Arguments:
  • aFile – An nsIFile for the file or directory of the add-on to be temporarily installed.
Returns:

a Promise that rejects if the add-on is not a valid restartless add-on or if the same ID is already temporarily installed.
AddonManager.isInstallAllowed()

Checks whether a particular source is allowed to install add-ons of a given mimetype.

Arguments:
  • aMimetype – The mimetype of the add-on
  • aInstallingPrincipal – The nsIPrincipal that initiated the install
Returns:

true if the source is allowed to install this mimetype
AddonManager.isInstallEnabled()

Checks whether installation is enabled for a particular mimetype.

Arguments:
  • aMimetype – The mimetype to check
Returns:

true if installation is enabled for the mimetype
AddonManager.isReady

Boolean indicating whether AddonManager startup has completed.

AddonManager.mapURIToAddonID()

Synchronously map a URI to the corresponding Addon ID.

Mappable URIs are limited to in-application resources belonging to the add-on, such as Javascript compartments, XUL windows, XBL bindings, etc. but do not include URIs from meta data, such as the add-on homepage.

Arguments:
  • aURI – nsIURI to map to an addon id
Returns:

string containing the Addon ID or null
AddonManager.markProviderSafe()

Mark a provider as safe to access via AddonManager APIs, before its startup has completed.

Normally a provider isn’t marked as safe until after its (synchronous) startup() method has returned. Until a provider has been marked safe, it won’t be used by any of the AddonManager APIs. markProviderSafe() allows a provider to mark itself as safe during its startup; this can be useful if the provider wants to perform tasks that block startup, which happen after its required initialization tasks and therefore when the provider is in a safe state.

Arguments:
  • aProvider – Provider object to mark safe
AddonManager.notifyAddonChanged()

Notifies all providers that an add-on has been enabled when that type of add-on only supports a single add-on being enabled at a time. This allows the providers to disable theirs if necessary.

Arguments:
  • aID – The ID of the enabled add-on
  • aType – The type of the enabled add-on
  • aPendingRestart – A boolean indicating if the change will only take place the next time the application is restarted
AddonManager.observe()

Notified when a preference we’re interested in has changed.

AddonManager.registerProvider()

Registers a new AddonProvider.

Arguments:
  • aProvider (string) – The provider to register
  • aTypes (Array.<string>) – An optional array of add-on types
AddonManager.removeAddonListener()

Removes an AddonListener if the listener is registered.

Arguments:
  • aListener (object) – The AddonListener to remove
AddonManager.removeInstallListener()

Removes an InstallListener if the listener is registered.

Arguments:
  • aListener – The InstallListener to remove
AddonManager.removeManagerListener()

Removes an AddonManagerListener if the listener is registered.

Arguments:
  • aListener (AddonManagerListener) – The listener to remove
AddonManager.removeStartupChange()

Removes a startup change for an add-on.

Arguments:
  • aType – The type of change
  • aID – The ID of the add-on
AddonManager.removeTypeListener()

Removes an TypeListener if the listener is registered.

Arguments:
  • aListener – The TypeListener to remove
AddonManager.removeUpgradeListener()

Removes an UpgradeListener if the listener is registered.

Arguments:
  • aInstanceID – The instance ID of the addon to remove
AddonManager.shouldAutoUpdate()

Determines whether an Addon should auto-update or not.

Arguments:
  • aAddon – The Addon representing the add-on
Returns:

true if the addon should auto-update, false otherwise.
AddonManager.shutdownManager()

Shuts down the addon manager and all registered providers, this must clean up everything in order for automated tests to fake restarts.

Returns:null – Promise that resolves when all providers and dependent modules have finished shutting down
AddonManager.shutdownState()

Report the current state of asynchronous shutdown

AddonManager.startup()

Initializes the AddonManager, loading any known providers and initializing them.

AddonManager.unregisterProvider()

Unregisters an AddonProvider.

Arguments:
  • aProvider – The provider to unregister
Returns:

Whatever the provider’s ‘shutdown’ method returns (if anything). For providers that have async shutdown methods returning Promises, the caller should wait for that Promise to resolve.
AddonManager.updateAddonAppDisabledStates()

Notifies all providers they need to update the appDisabled property for their add-ons in response to an application change such as a blocklist update.

AddonManager.updateAddonRepositoryData()

Notifies all providers that the repository has updated its data for installed add-ons.