AddonManager Reference

class AddonManager()

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

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.

AddonManager.addAddonListener(aListener)

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

Arguments

  • aListener (AddonManagerListener()) – The AddonListener to add.

AddonManager.addInstallListener(aListener)

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

Arguments

  • aListener – The InstallListener to add

AddonManager.addManagerListener(aListener)

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

Arguments

  • aListener (AddonManagerListener()) – The listener to add

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

AddonManager.addTypeListener(aListener)

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

Arguments

  • aListener (TypeListener()) – The TypeListener to add

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

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

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

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

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

See also

  • callProvider

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.

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

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.

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

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 –

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

AddonManager.getAllAddons()

Asynchronously gets all installed add-ons.

AddonManager.getAllInstalls()

Asynchronously gets all current AddonInstalls.

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

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.

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

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

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

AddonManager.init
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

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

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

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.

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.

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

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.

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

AddonManager.isReady

Boolean indicating whether AddonManager startup has completed.

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

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.

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

AddonManager.observe()

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

See also

  • nsIObserver

AddonManager.registerProvider(aProvider, aTypes)

Registers a new AddonProvider.

Arguments

  • aProvider (string()) – The provider to register

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

AddonManager.removeAddonListener(aListener)

Removes an AddonListener if the listener is registered.

Arguments

  • aListener (object()) – The AddonListener to remove

AddonManager.removeInstallListener(aListener)

Removes an InstallListener if the listener is registered.

Arguments

  • aListener – The InstallListener to remove

AddonManager.removeManagerListener(aListener)

Removes an AddonManagerListener if the listener is registered.

Arguments

  • aListener (AddonManagerListener()) – The listener to remove

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

AddonManager.removeTypeListener(aListener)

Removes an TypeListener if the listener is registered.

Arguments

  • aListener – The TypeListener to remove

AddonManager.removeUpgradeListener(aInstanceID)

Removes an UpgradeListener if the listener is registered.

Arguments

  • aInstanceID – The instance ID of the addon to remove

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.

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

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.

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.