Extension Manager:API Rewrite:API
AddonManager
The AddonManager is the global API that allows access to all types of add-ons. It hides the differences in implementations presenting a standard interface to developers.
getInstallForURL
Creates a new object representing an add-on installation from a url. Any information provided will be replaced with real details from the add-on once available. This method operates asynchronously.
- url
- The URL to install the add-on from
- callback
- A function to pass an AddonInstall to when created
- mimetype
- The mimetype of the add-on to be downloaded.
- hash
- A hash to compare the downloaded add-on to (optional).
- name
- A human readable name for the add-on to be displayed during install (optional).
- iconURL
- An icon used to represent the add-on during install (optional).
- version
- The version of the add-on to be installed (optional).
- loadgroup
- An nsILoadGroup to attach any download channels to for the purposes of correct cookie sending.
getInstallForFile
Creates a new object representing an add-on installation from a local file, properties for the install will be loaded out of the file. This method operates asynchronously.
- file
- A
nsIFileto install the add-on from - callback
- A function that will be passed the AddonInstall for the installation
- mimetype
- The mimetype of the add-on to be downloaded. If not provided file based detection will be used. (optional)
getAllInstalls
Returns the list of known add-on installs. This method operates asynchronously.
- callback
- A function that will be passed an array of AddonInstalls
getInstallsByTypes
Returns the list of known add-on installs optionally restricting to a set of types of add-ons. This method operates asynchronously.
- types
- An array of types of add-ons to return (optional)
- callback
- A function that will be passed an array of AddonInstalls
startInstallation
Starts the install process for multiple AddonInstalls calling the registered extIWebInstallListener to notify about blocked or started installs. This is primarily intended to start installs triggered by content webpages.
- mimetype
- The mimetype of the installs.
- source
- The source nsIDOMWindow that triggered the installs (optional).
- uri
- The nsIURI that triggered the installs (optional).
- installs
- An array of AddonInstalls.
addInstallListener
Adds a listener that will be notified about any events in any install. The same listener will not be added multiple times.
- listener
- An InstallListener
removeInstallListener
Removes a previously added install listener.
- listener
- An InstallListener
getAllAddons
Gets all the installed add-ons. This method operates asynchronously.
- callback
- A function that will be passed an array Addons
getAddonByID
Gets an installed add-on. This method operates asynchronously.
- id
- The ID of the add-on to retrieve
- callback
- A function that will be passed an Addon representing the add-on or null if there is no installed add-on with the given ID
getAddonsByIDs
Gets an array installed add-ons with specific IDs. This method operates asynchronously.
- ids
- An array of IDs of the add-ons to retrieve
- callback
- A function that will be passed an array Addons in the same order as the ids array
getAddonsByTypes
Gets an array of the installed add-ons optionally restricting to a set of types. This method operates asynchronously.
- types
- An array of types of add-ons to return (optional)
- callback
- A function that will be passed an array of Addons representing the installed add-ons
getAddonsWithOperationsByTypes
Gets an array of add-ons that currently have pending operations requiring an application restart to complete. This method operates asynchronously.
- types
- An array of types of add-ons to return (optional)
- callback
- A function that will be passed an array of Addons representing the add-ons with pending operations.
addAddonListener
Adds a listener that will be notified about changes to add-on states for all installed add-ons. The same listener will not be added multiple times.
- listener
- An AddonListener
removeAddonListener
Removes a previously added add-on listener.
- listener
- An AddonListener
Addon
An Addon represents an instance of an installed add-on. Some of these listed properties may be relevant for only XPI style add-ons.
Required Properties
id (string, readonly)
The ID of the add-on. No other installed add-on will have the same ID.
version (string, readonly)
The version of the add-on.
type (string, readonly)
The type of the add-on.
isCompatible (boolean, readonly)
True or false depending on whether the add-on is compatible with the current version and platform of the application.
providesUpdatesSecurely (boolean, readonly)
True if the add-on has a secure means of updating.
blocklistState (number, readonly)
The current blocklist state of this add-on.
appDisabled (boolean, readonly)
True if this add-on cannot be used in the application based on version compatibility, dependencies and blocklisting.
userDisabled (boolean)
True if the user wants this add-on to be disabled. Listeners may be notified of the change asynchronously.
scope (number, readonly)
Indicates what scope the add-on is installed in, per profile, user, system or application.
isActive (boolean, readonly)
True if the add-on is currently functional. For some add-ons this will change immediately based on the appDisabled and userDisabled properties, for others it will only change after an application restart.
name (string, readonly)
The name of the add-on.
creator (string, readonly)
The creator of the add-on.
pendingOperations (number, readonly)
A bitfield holding all of the current operations that are waiting to be performed for this add-on. Operations are generally deferred when a restart is necessary to accomplish them.
permissions (number, readonly)
A bitfield holding all the the operations that can be performed on this add-on. Operations my be restricted based on system policies (e.g. the system administrator may not allow certain add-ons to be uninstalled), add-on type (e.g. themes may not be disabled) or add-on state (e.g. an incompatible add-on cannot be enabled).
Optional Properties
description (string, readonly)
The description of the add-on.
installDate (Date, readonly, optional)
The Date that the add-on was first installed.
updateDate (Date, readonly, optional)
The Date that the add-on was most recently updated.
optionsURL (string, readonly, optional)
The url of the options dialog to display for this add-on.
aboutURL (string, readonly, optional)
The url of the about dialog to display for this add-on.
iconURL (string, readonly, optional)
The url of the icon that represents this add-on.
homepageURL (string, readonly)
The homepageURL of the add-on.
screenshots (array of string, readonly, optional)
The urls of preview images for the add-ons.
developers (string array, readonly, optional)
The developers of the add-on.
translators (string array, readonly, optional)
The translators of the add-on.
contributors (string array, readonly, optional)
The contributors of the add-on.
applyBackgroundUpdates (boolean, automatic)
Whether updates found in the background for this add-on will be applied automatically.
pendingUpgrade (Addon, readonly, optional)
If a this add-on will be replaced on the next restart this property will hold the new Addon object.
install (AddonInstall, readonly, optional)
The AddonInstall that will install this addon. Only available if this addon is in the process of being installed.
Required Methods
isCompatibleWith
Tests whether this add-on is known to be compatible with a particular application and platform version.
- appVersion
- An application version to test against
- platformVersion
- A platform version to test against
findUpdates
Starts an update check for this add-on. This will perform asynchronously and deliver results to the given listener.
- listener
- An UpdateListener for the update process
- reason
- A reason code for performing the update. Can be one of the following:
- AddonManager.UPDATE_WHEN_USER_REQUESTED
- AddonManager.UPDATE_WHEN_NEW_APP_DETECTED
- AddonManager.UPDATE_WHEN_NEW_APP_INSTALLED
- AddonManager.UPDATE_WHEN_PERIODIC_UPDATE
- AddonManager.UPDATE_WHEN_ADDON_INSTALLED
- appVersion
- An application version to check for updates for (optional)
- platformVersion
- A platform version to check for updates for (optional)
Optional Methods
uninstall
Uninstalls this add-on. If possible the uninstall will happen immediately otherwise it will wait until the next application restart. Listeners may be notified of the uninstall asynchronously.
This method must be defined if an add-on has the permission PERM_CAN_UNINSTALL.
cancelUninstall
Cancels uninstalling an add-on if it is pending uninstall.
This method must be defined if an add-on ever has the pendingOperation PENDING_UNINSTALL.
hasResource
Checks whether a file resource is available for this add-on. For XPI style add-ons for example it tests whether the named file was included in the package.
- path
- A "/" separated path for the resource.
getResourceURL
Gets a url to the file resource.
- path
- A "/" separated path for the resource.
AddonInstall
Represents an add-on installation through various states from being available through to being installed. Some of the properties may not be accurate depending on where the install came from and may change once the add-on has been downloaded and checked.
name (string, readonly)
The name of the add-on being installed.
version (string, readonly)
The version of the add-on being installed.
iconURL (string, readonly)
The icon of the add-on being installed.
infoURL (string, readonly)
The URL of release notes for this install.
type (string, readonly)
The type of the add-on being installed.
state (number, readonly)
The state of the installation.
sourceURL (string, readonly)
The url that the add-on is being installed from.
file (nsIFile, readonly)
The file that the add-on is being installed from. This may be null if the add-on is coming from the internet and has yet to be downloaded.
progress (number, readonly)
The progress of any necessary downloads.
maxProgress (number, readonly)
The expected size of any necessary downloads or -1 if unknown.
certificate (nsIX509Cert, readonly)
If the add-on to be installed is signed this is the certificate of the signer. Only available after downloading is complete.
certName (string, readonly)
If the add-on to be installed is signed this is the simple display name of the signer.
existingAddon (Addon readonly)
The #Addon that this install will update. May be null if it isn't updating anything installed. This is guaranteed to be correct after downloading is complete but may be set earlier.
addon (Addon readonly)
The full #Addon that this install will install. Only available after downloading is complete.
install
Starts the install process for the add-on, continuing from whatever state this AddonInstall is already in.
cancel
Stops the install process for this AddonInstall. Normally the install will fall into the Cancelled state and not be restartable.
addListener
Adds an #InstallListener that will only receive events for this install instance.
removeListener
Removes an #InstallListener registered to receive events for this install instance.
AddonListener
AddonListeners are notified about changes to the state of add-ons. Certain state changes may not take effect until the next application restart.
onEnabling
Called when an add-on is about to be enabled.
- addon
- The Addon that has been enabled
- needsRestart
- True if an application restart is necessary for the change to take effect
onEnabled
Called when an add-on has been enabled.
- addon
- The Addon that has been enabled
onDisabling
Called when an add-on is about to be disabled.
- addon
- The Addon that has been disabled
- needsRestart
- True if an application restart is necessary for the change to take effect
onDisabled
Called when an add-on has been disabled.
- addon
- The Addon that has been disabled
onInstalling
Called when a new add-on is about to be installed.
- addon
- The Addon that has been installed
- install
- The AddonInstall that is responsible for the install or null if there is no AddonInstall managing the install.
- needsRestart
- True if an application restart is necessary for the change to take effect
onInstalled
Called when a new add-on has been installed.
- addon
- The Addon that has been installed.
onUninstalling
Called when an add-on is about to be uninstalled.
- addon
- The Addon that has been uninstalled
- needsRestart
- True if an application restart is necessary for the change to take effect
onUninstalled
Called when an add-on has been uninstalled.
- addon
- The Addon that has been uninstalled
onOperationCancelled
Called when a pending operation for an add-on is cancelled.
- addon
- The Addon that has had a pending operation cancelled
UpdateListener
Notification about events during an update check for an add-on are passed to an update listener. For a single update check:
- Either
onCompatibilityUpdateAvailableononNoCompatibilityUpdateAvailablewill be called once. - Either
onUpdateAvailableoronNoUpdateAvailablewill be called once. onUpdateFinishedwill always be called last.
onCompatibilityUpdateAvailable
Called when the update check found compatibility information for the application and platform version that the update check was being performed for.
- addon
- The Addon that was being checked for updates
onNoCompatibilityUpdateAvailable
Called when the update check found no new compatibility information for the application and platform version that the update check was being performed for.
- addon
- The Addon that was being checked for updates
onUpdateAvailable
Called when a new version of an add-on has been found for install.
- addon
- The Addon that was being checked for updates
- install
- An AddonInstall for the updated version
onNoUpdateAvailable
Called when no new version of an add-on has been found for install.
- addon
- The Addon that was being checked for updates
onUpdateFinished
Called when the update check is complete.
- addon
- The Addon that was being checked for updates
- error
- An error code or 0 if there was no error
InstallListener
An InstallListener is notified during add-on downloads and installs.
onNewInstall
Called when a new instance of AddonInstall is created, primarily so UI can display some kind of progress for all installs.
- install
- The AddonInstall representing the install
onDownloadStarted
Called when downloading begins for an add-on install. Only called for add-ons that need to be downloaded. A listener may return false to cancel the download.
- install
- The AddonInstall representing the install
onDownloadProgress
Called as data is received during a download. Check the AddonInstall's progress property for the amount of data downloaded and the maxProgress property for the total data expected. A listener may return false to cancel the download.
- install
- The AddonInstall representing the install
onDownloadEnded
Called when downloading completes successfully for an add-on install. Only called for add-ons that need to be downloaded.
- install
- The AddonInstall representing the install
onDownloadCancelled
Called when downloading is cancelled. Only called for add-ons that need to be downloaded.
- install
- The AddonInstall representing the install
onDownloadFailed
Called if there is some error downloading the add-on. Only called for add-ons that need to be downloaded.
- install
- The AddonInstall representing the install
- error
- An exception representing the error
onInstallStarted
Called when installation of an add-on begins. A listener may return false to cancel the install.
- install
- The AddonInstall representing the install
onInstallEnded
Called when installation of an add-on is complete. The newly installed add-on may require a restart in order to become active.
- install
- The AddonInstall representing the install
- addon
- The newly installed Addon
onInstallCancelled
Called when installation is cancelled.
- install
- The AddonInstall representing the install
onInstallFailed
Called when there is a failure installing the add-on.
- install
- The AddonInstall representing the install
- error
- An exception representing the error
onExternalInstall
Called when an add-on is installed through some system other than an AddonInstall.