AddonManager Reference

class AddonManager()

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

AddonManager.beforeShutdown

Async shutdown barrier which blocks the start of AddonManager shutdown. Callers should add blockers to this barrier if they need to complete add-on manager operations before it shuts down.

AddonManager.init

AddonManager.isReady

Boolean indicating whether AddonManager startup has completed.

AddonManager.readyPromise

A promise that is resolved when the AddonManager startup has completed. This may be rejected if startup of the AddonManager is not successful, or if shutdown is started before the AddonManager has finished starting.

static AddonManager._verifyThirdPartyInstall(browser, url, install, info, source)

Verify whether we need to show the 3rd party install prompt.

Bypass the third party install prompt if this is an install:

• is an install from a recognized source

• is a an addon that can bypass the panel, such as a recommended addon

Arguments:

• browser (browser) – browser user is installing from

• url (nsIURI) – URI for the principal of the installing source

• install (AddonInstallWrapper)

• info (Object) – information such as addon wrapper

• info.addon (AddonWrapper)

• source (string) – simplified string describing source of install and is generated based on the installing principal and checking against site permissions and enterprise policy. It may be one of “AMO”, “local” or “other”.

Returns:

Promise – Rejected when the installation should not proceed.

static AddonManager.addAddonListener(aListener)

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

Arguments:

• aListener (AddonManagerListener) – The AddonListener to add.

static AddonManager.addInstallListener(aListener)

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

Arguments:

• aListener – The InstallListener to add

static AddonManager.addManagerListener(aListener)

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

Arguments:

• aListener (AddonManagerListener) – The listener to add

static AddonManager.addStartupChange(aType, aID)

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

static AddonManager.addUpgradeListener(aInstanceID, aCallback)

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

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

static AddonManager.callAddonListeners(aMethod)

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

static AddonManager.callInstallListeners(aMethod, aExtraListeners)

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

static AddonManager.callManagerListeners(aMethod)

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

static AddonManager.callProviders(aMethod)

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

static AddonManager.escapeAddonURI(aAddon, aUri, aAppVersion)

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.

static AddonManager.getActiveAddons(aTypes)

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

static AddonManager.getAddonByID(aID)

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.

static AddonManager.getAddonBySyncGUID(aGUID)

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

static AddonManager.getAddonsByIDs(aIDs)

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 –

static AddonManager.getAddonsByTypes(aTypes)

Asynchronously gets add-ons of specific types.

Arguments:

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

static AddonManager.getAllAddons()

Asynchronously gets all installed add-ons.

static AddonManager.getAllInstalls()

Asynchronously gets all current AddonInstalls.

static AddonManager.getInstallForFile(aFile, aMimetype, aTelemetryInfo, aUseSystemLocation)

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

• aTelemetryInfo – An optional object which provides details about the installation source included in the addon manager telemetry events.

• aUseSystemLocation – If true the addon is installed into the system profile location.

Throws:

if the aFile or aCallback arguments are not specified

static AddonManager.getInstallForURL(aUrl, aOptions={})

Asynchronously gets an AddonInstall for a URL.

Arguments:

• aUrl – The string represenation of the URL where the add-on is located

• aOptions (Object) – Additional options for this install

• aOptions.hash (string) – An optional hash of the add-on

• aOptions.name (string) – An optional placeholder name while the add-on is being downloaded

• aOptions.icons (string|Object) – Optional placeholder icons while the add-on is being downloaded

• aOptions.version (string) – An optional placeholder version while the add-on is being downloaded

• aOptions.browser (XULElement) – An optional <browser> element for download permissions prompts.

• aOptions.triggeringPrincipal (nsIPrincipal) – The principal which is attempting to install the add-on.

• aOptions.telemetryInfo (Object) – An optional object which provides details about the installation source included in the addon manager telemetry events.

Throws:

if aUrl is not specified or if an optional argument of an improper type is passed.

static AddonManager.getInstallsByTypes(aTypes)

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

static AddonManager.getPreferredIconURL(aAddon, aSize, aWindow)

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

static AddonManager.getSitePermsAddonInstallForWebpage(aBrowser:, aInstallingPrincipal, aSitePerm)

Get a SitePermsAddonInstall instance.

Arguments:

• aBrowser: (Element) – The optional browser element that started the install

• aInstallingPrincipal (nsIPrincipal)

• aSitePerm (String)

Throws:

Components.Exception – Will throw an error if: - the AddonManager is not initialized - aInstallingPrincipal is not a nsIPrincipal - aInstallingPrincipal scheme is not https - aInstallingPrincipal is a public etld - aInstallingPrincipal is a plain ip address - aInstallingPrincipal is in the blocklist - aSitePerm is not a gated permission - aBrowser is not null and not an element

Returns:

Promise.<(SitePermsAddonInstall|null)> – The promise will resolve with null if there are no provider with a getSitePermsAddonInstallForWebpage method. In practice, this should only be the case when SitePermsAddonProvider is not enabled, i.e. when dom.sitepermsaddon-provider.enabled is false.

static AddonManager.getStartupChanges(aType)

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

static AddonManager.hasAddonType(addonType)

Arguments:

• addonType (string)

Returns:

boolean – Whether there is a provider that provides the given addon type.

static AddonManager.installAddonFromAOM(browser, uri, install)

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

static AddonManager.installAddonFromWebpage(aMimetype, aBrowser, aInstallingPrincipal, aInstall, aDetails)

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

Arguments:

• aMimetype – The mimetype of the add-on being installed

• aBrowser – The optional browser element that started the install

• aInstallingPrincipal – The nsIPrincipal that initiated the install

• aInstall – The AddonInstall to be installed

• aDetails – Additional optional details

• aDetails.hasCrossOriginAncestor – Boolean value set to true if any of cross-origin ancestors of the triggering frame (if set to true the installation will be denied).

static AddonManager.installBuiltinAddon(aBase)

Installs an add-on from a built-in location

(ie a resource: url referencing assets shipped with the application)

Arguments:

• aBase – A string containing the base URL. Must be a resource: URL.

Returns:

a Promise that resolves when the addon is installed.

static AddonManager.installSitePermsAddonFromWebpage(aBrowser, aInstallingPrincipal, aPermission)

Starts installation of a SitePermsAddonInstall notifying the registered web install listener of a blocked or started install.

Arguments:

• aBrowser – The optional browser element that started the install

• aInstallingPrincipal – The nsIPrincipal that initiated the install

• aPermission – The permission to install

Throws:

Components.Exception – Will throw an error if the AddonManager is not initialized or if aInstallingPrincipal is not a nsIPrincipal.

Returns:

Promise – A promise that will resolve when the user installs the addon. The promise will reject if the user blocked the install, or if the addon can’t be installed (e.g. the principal isn’t supported).

static AddonManager.installTemporaryAddon(aFile)

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.

static AddonManager.isInstallAllowed(aMimetype, aInstallingPrincipal)

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

static AddonManager.isInstallAllowedByPolicy(aInstallingPrincipal, aInstall, explicit)

Checks whether a particular source is allowed to install add-ons based on policy.

Arguments:

• aInstallingPrincipal – The nsIPrincipal that initiated the install

• aInstall – The AddonInstall to be installed

• explicit – If this is set, we only return true if the source is explicitly blocked via policy.

Returns:

boolean By default, returns true if the source is blocked by policy or there is no policy. If explicit is set, only returns true of the source is blocked by policy, false otherwise. This is needed for handling inverse cases.

static AddonManager.isInstallEnabled(aMimetype)

Checks whether installation is enabled for a particular mimetype.

Arguments:

• aMimetype – The mimetype to check

Returns:

true if installation is enabled for the mimetype

static AddonManager.markProviderSafe(aProvider)

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

static AddonManager.maybeInstallBuiltinAddon(aID, aVersion, aBase)

Like installBuiltinAddon, but only installs the addon at aBase if an existing built-in addon with the ID aID and version doesn’t already exist.

Arguments:

• aID (string) – The ID of the add-on being registered.

• aVersion (string) – The version of the add-on being registered.

• aBase (string) – A string containing the base URL. Must be a resource: URL.

Returns:

a Promise that resolves when the addon is installed.

static AddonManager.notifyAddonChanged(aID, aType, aPendingRestart)

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

static AddonManager.observe()

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

static AddonManager.registerProvider(aProvider, aTypes)

Registers a new AddonProvider.

Arguments:

• aProvider (string) – The provider to register

• aTypes (Array.<string>) – An optional array of add-on types

static AddonManager.removeAddonListener(aListener)

Removes an AddonListener if the listener is registered.

Arguments:

• aListener (object) – The AddonListener to remove

static AddonManager.removeInstallListener(aListener)

Removes an InstallListener if the listener is registered.

Arguments:

• aListener – The InstallListener to remove

static AddonManager.removeManagerListener(aListener)

Removes an AddonManagerListener if the listener is registered.

Arguments:

• aListener (AddonManagerListener) – The listener to remove

static AddonManager.removeStartupChange(aType, aID)

Removes a startup change for an add-on.

Arguments:

• aType – The type of change

• aID – The ID of the add-on

static AddonManager.removeUpgradeListener(aInstanceID)

Removes an UpgradeListener if the listener is registered.

Arguments:

• aInstanceID – The instance ID of the addon to remove

static AddonManager.shouldAutoUpdate(aAddon)

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.

static 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

static AddonManager.shutdownState()

Report the current state of asynchronous shutdown

static AddonManager.startup()

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

static AddonManager.uninstallSystemProfileAddon(aID)

Uninstall an addon from the system profile location.

Arguments:

• aID (string) – The ID of the addon to remove.

Returns:

A promise that resolves when the addon is uninstalled.

static AddonManager.unregisterProvider(aProvider)

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.

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

static AddonManager.updateAddonRepositoryData()

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