Extension Manager:API Rewrite:API: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(Replaced content with 'The information here has been transferred to the [https://developer.mozilla.org/en/Addons/Add-on_Manager Mozilla Developer Network].')
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
=AddonManager=
The information here has been transferred to the [https://developer.mozilla.org/en/Addons/Add-on_Manager Mozilla Developer Network].
 
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|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 <code>nsIFile</code> to install the add-on from
;callback :A function that will be passed the [[#AddonInstall|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 [[#AddonInstall|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 [[#AddonInstall|AddonInstalls]]
 
==startInstallation==
 
Starts the install process for multiple [[#AddonInstall|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 [[#AddonInstall|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|InstallListener]]
 
==removeInstallListener==
 
Removes a previously added install listener.
 
;listener :An [[#InstallListener|InstallListener]]
 
==getAllAddonsBy==
 
Gets all the installed add-ons. This method operates asynchronously.
 
;callback :A function that will be passed an array [[#Addon|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|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 [[#Addon|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 [[#Addon|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 [[#Addon|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|AddonListener]]
 
==removeAddonListener==
 
Removes a previously added add-on listener.
 
;listener :An [[#AddonListener|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.
 
===description (string, readonly)===
 
The description 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==
 
===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.
 
===updateAutomatically (boolean, automatic)===
 
Whether updates found 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|AddonInstall]], readonly, optional)===
 
The [[#AddonInstall|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|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|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|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|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|Addon]] that has been enabled
 
==onDisabling==
 
Called when an add-on is about to be disabled.
 
;addon :The [[#Addon|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|Addon]] that has been disabled
 
==onInstalling==
 
Called when a new add-on is about to be installed.
 
;addon :The [[#Addon|Addon]] that has been installed
;install :The [[#AddonInstall|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|Addon]] that has been installed.
 
==onUninstalling==
 
Called when an add-on is about to be uninstalled.
 
;addon :The [[#Addon|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|Addon]] that has been uninstalled
 
==onOperationCancelled==
 
Called when a pending operation for an add-on is cancelled.
 
;addon :The [[#Addon|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 <code>onCompatibilityUpdateAvailable</code> on <code>onNoCompatibilityUpdateAvailable</code> will be called once.
* Either <code>onUpdateAvailable</code> or <code>onNoUpdateAvailable</code> will be called once.
* <code>onUpdateFinished</code> will 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|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|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|Addon]] that was being checked for updates
;install :An [[#AddonInstall|AddonInstall]] for the updated version
 
==onNoUpdateAvailable==
 
Called when no new version of an add-on has been found for install.
 
;addon :The [[#Addon|Addon]] that was being checked for updates
 
==onUpdateFinished==
 
Called when the update check is complete.
 
;addon :The [[#Addon|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.
 
==onDownloadStarted==
 
Called when downloading begins for an add-on install. Only called for add-ons that need to be downloaded. A listener may return <code>false</code> to cancel the download.
 
;install :The [[#AddonInstall|AddonInstall]] representing the install
 
==onDownloadProgress==
 
Called as data is received during a download. Check the [[#AddonInstall|AddonInstall's]] progress property for the amount of data downloaded and the maxProgress property for the total data expected. A listener may return <code>false</code> to cancel the download.
 
;install :The [[#AddonInstall|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|AddonInstall]] representing the install
 
==onDownloadCancelled==
 
Called when downloading is cancelled. Only called for add-ons that need to be downloaded.
 
;install :The [[#AddonInstall|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|AddonInstall]] representing the install
;error :An exception representing the error
 
==onInstallStarted==
 
Called when installation of an add-on begins. A listener may return <code>false</code> to cancel the install.
 
;install :The [[#AddonInstall|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|AddonInstall]] representing the install
;addon :The newly installed [[#Addon|Addon]]
 
==onInstallCancelled==
 
Called when installation is cancelled.
 
;install :The [[#AddonInstall|AddonInstall]] representing the install
 
==onInstallFailed==
 
Called when there is a failure installing the add-on.
 
;install :The [[#AddonInstall|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.
 
;addon :The newly installed [[#Addon|Addon]]
;existingAddon :An [[#Addon|Addon]] that will be replaced by this install or null if no add-on is being replaced
;requiresRestart :True if the installation requires a restart

Latest revision as of 02:37, 4 June 2010

The information here has been transferred to the Mozilla Developer Network.

Retrieved from "https://wiki.mozilla.org/index.php?title=Extension_Manager:API_Rewrite:API&oldid=227675"