Addon

  • Revision slug: Addons/Add-on_Manager/Addon
  • Revision title: Addon
  • Revision id: 65104
  • Created:
  • Creator: gps
  • Is current revision? No
  • Comment document optional syncGUID field; 27 words added

Revision Content

{{ gecko_minversion_header("2.0") }}

An Addon represents an add-on that is either installed or can be installed. Instances can be created using the many getAddon methods on the {{ AMInterface("AddonManager") }} object.

The interface can represent many different kinds of add-ons and as such some of the properties are considered "required" and others "optional" which means that the optional property may not exist on Addon instances for some types of add-ons. API consumers should take care to verify the existence of these properties before relying on them.

Method overview

void isCompatibleWith(in string appVersion, in string platformVersion)
void findUpdates(in {{ AMInterface("UpdateListener") }} listener, in integer reason, in string appVersion, in string platformVersion)
void uninstall()
void cancelUninstall()
boolean hasResource(in string path)
{{ Interface("nsIURI") }} getResourceURI(in string path)

Required properties

Attribute Type Description
appDisabled boolean True if this add-on cannot be used in the application based on version compatibility, dependencies and blocklisting.
blocklistState integer The current blocklist state of this add-on, see {{ Interface("nsIBlocklistService") }} for possible values.
creator {{ AMInterface("AddonAuthor") }} The creator of the add-on.
id string The ID of the add-on. No other installed add-on will have the same ID.
isActive boolean 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.
isCompatible boolean True or false depending on whether the add-on is compatible with the current application version and platform version.
isPlatformCompatible boolean True or false depending on whether the add-on is compatible with the current operating system.
name string The name of the add-on.
pendingOperations integer 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 integer 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).
providesUpdatesSecurely boolean True if the add-on has a secure means of updating or cannot be updated at all.
scope integer Indicates what scope the add-on is installed in, per profile, user, system or application.
type string The type of the add-on.
userDisabled boolean True if the user wants this add-on to be disabled.
version string The version of the add-on.

Optional properties

Attribute Type Description
aboutURL string The URL of the about dialog to display for this add-on. This is passed to {{ domxref("window.openDialog()") }} when presenting the about dialog. If you don't provide an aboutURL, a generic about dialog is displayed. The dialog receives the Addon object representing your add-on as a parameter.
applyBackgroundUpdates integer Indicates whether updates found in the background for this add-on will be applied automatically. See auto update values.
contributors {{ AMInterface("AddonAuthor") }}[] An array of strings holding the contributors of the add-on.
description string The description of the add-on.
developers {{ AMInterface("AddonAuthor") }}[] An array of strings holding the developers of the add-on.
homepageURL string The homepageURL of the add-on.
iconURL string The url of the icon that represents this add-on.
install {{ AMInterface("AddonInstall") }} The {{ AMInterface("AddonInstall") }} that will install this addon. Only available if this addon is in the process of being installed.
installDate Date The Date that the add-on was first installed.
optionsURL string The url of the options dialog to display for this add-on.
pendingUpgrade {{ AMInterface("Addon") }} If a this add-on will be replaced on the next restart this property will hold the new {{ AMInterface("Addon") }} object.
releaseNotesURI {{ Interface("nsIURI") }} A uri for release notes for this version.
screenshots {{ AMInterface("AddonScreenshot") }}[] An array of urls of preview images for the add-on.
size integer The size of the add-on's files in bytes. For an add-on that have not yet been downloaded this may be an estimated value.
sourceURI {{ Interface("nsIURI") }} The uri that this add-on was installed from.
syncGUID string String GUID to identify the add-on in Sync. The GUID is generated randomly and is made consistent across devices during sync.
translators {{ AMInterface("AddonAuthor") }}[] An array of strings holding the translators of the add-on.
updateDate Date The Date that the add-on was most recently updated.
operationsRequiringRestart integer A bitfield holding all of the operations that will require a restart to complete for this add-on.
fullDescription string  
developerComments string  
eula string  
icon64URL string  
supportURL string  
contributionURL string  
contributionAmount string  
averageRating number  
reviewCount integer  
reviewURL string  
totalDownloads integer  
weeklyDownloadss integer  
dailyUsers integer  
repositoryStatus integer  

Required Methods

isCompatibleWith()

Tests whether this add-on is known to be compatible with a particular application and platform version.

void isCompatibleWith(
  in string appVersion,
  in string platformVersion
)
Parameters
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.

void findUpdates(
  in {{ AMInterface("UpdateListener") }} listener,
  in integer reason,
  in string appVersion,
  in string platformVersion
)
Parameters
listener
An {{ AMInterface("UpdateListener") }} for the update process
reason
A reason code for performing the update
appVersion
An application version to check for updates for
platformVersion
A platform version to check for updates for

Optional Methods

uninstall()

Uninstalls this add-on. If possible the uninstall will happen immediately otherwise it will wait until the next application restart.

This method must be defined if an add-on has the permission PERM_CAN_UNINSTALL.

void uninstall(
)

cancelUninstall()

Cancels uninstalling an add-on if it is pending uninstall.

This method must be defined if an add-on has the pendingOperation PENDING_UNINSTALL.

void cancelUninstall(
)

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.

boolean hasResource(
  in string path
)
Parameters
path
A "/" separated path for the resource.

getResourceURI()

Gets an {{ Interface("nsIURI") }} to the file resource for this add-on.

{{ Interface("nsIURI") }} getResourceURI(
  in string path
)
Parameters
path
A "/" separated path for the resource.

Revision Source

<p>{{ gecko_minversion_header("2.0") }}</p>
<p>An Addon represents an add-on that is either installed or can be installed. Instances can be created using the many getAddon methods on the {{ AMInterface("AddonManager") }} object.</p>
<p>The interface can represent many different kinds of add-ons and as such some of the properties are considered "required" and others "optional" which means that the optional property may not exist on Addon instances for some types of add-ons. API consumers should take care to verify the existence of these properties before relying on them.</p>
<h2>Method overview</h2>
<table class="standard-table"> <tbody> <tr> <td><code>void <a href="#isCompatibleWith()">isCompatibleWith</a>(in string appVersion, in string platformVersion)</code></td> </tr> <tr> <td><code>void <a href="#findUpdates()">findUpdates</a>(in {{ AMInterface("UpdateListener") }} listener, in integer reason, in string appVersion, in string platformVersion)</code></td> </tr> <tr> <td><code>void <a href="#uninstall()">uninstall</a>()</code></td> </tr> <tr> <td><code>void <a href="#cancelUninstall()">cancelUninstall</a>()</code></td> </tr> <tr> <td><code>boolean <a href="#hasResource()">hasResource</a>(in string path)</code></td> </tr> <tr> <td>{{ Interface("nsIURI") }}<code> <a href="#getResourceURI()">getResourceURI</a>(in string path)</code></td> </tr> </tbody>
</table>
<h2>Required properties</h2>
<table class="standard-table" style="width: auto;"> <tbody> <tr> <td class="header">Attribute</td> <td class="header">Type</td> <td class="header">Description</td> </tr> <tr> <td><code>appDisabled</code></td> <td><code>boolean</code></td> <td>True if this add-on cannot be used in the application based on version compatibility, dependencies and blocklisting.</td> </tr> <tr> <td><code>blocklistState</code></td> <td><code>integer</code></td> <td>The current blocklist state of this add-on, see {{ Interface("nsIBlocklistService") }} for possible values.</td> </tr> <tr> <td><code>creator</code></td> <td><code>{{ AMInterface("AddonAuthor") }}</code></td> <td>The creator of the add-on.</td> </tr> <tr> <td><code>id</code></td> <td><code>string</code></td> <td>The ID of the add-on. No other installed add-on will have the same ID.</td> </tr> <tr> <td><code>isActive</code></td> <td><code>boolean</code></td> <td>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.</td> </tr> <tr> <td><code>isCompatible</code></td> <td><code>boolean</code></td> <td>True or false depending on whether the add-on is compatible with the current application version and platform version.</td> </tr> <tr> <td><code>isPlatformCompatible</code></td> <td><code>boolean</code></td> <td>True or false depending on whether the add-on is compatible with the current operating system.</td> </tr> <tr> <td><code>name</code></td> <td><code>string</code></td> <td>The name of the add-on.</td> </tr> <tr> <td><code>pendingOperations</code></td> <td><code>integer</code></td> <td>A bitfield holding all of the current <a href="/en/Addons/Add-on_Manager/AddonManager#Pending_operations" title="en/Addons/Add-on Manager/AddonManager#Pending operations">operations</a> that are waiting to be performed for this add-on. Operations are generally deferred when a restart is necessary to accomplish them.</td> </tr> <tr> <td><code>permissions</code></td> <td><code>integer</code></td> <td>A bitfield holding all the the <a href="/en/Addons/Add-on_Manager/AddonManager#Permissions" title="en/Addons/Add-on Manager/AddonManager#Permissions">operations</a> 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).</td> </tr> <tr> <td><code>providesUpdatesSecurely</code></td> <td><code>boolean</code></td> <td>True if the add-on has a secure means of updating or cannot be updated at all.</td> </tr> <tr> <td><code>scope</code></td> <td><code>integer</code></td> <td>Indicates what <a href="/en/Addons/Add-on_Manager/AddonManager#Installation_scopes" title="en/Addons/Add-on Manager/AddonManager#Installation scopes">scope</a> the add-on is installed in, per profile, user, system or application.</td> </tr> <tr> <td><code>type</code></td> <td><code>string</code></td> <td>The type of the add-on.</td> </tr> <tr> <td><code>userDisabled</code></td> <td><code>boolean</code></td> <td>True if the user wants this add-on to be disabled.</td> </tr> <tr> <td><code>version</code></td> <td><code>string</code></td> <td>The version of the add-on.</td> </tr> </tbody>
</table>
<h2>Optional properties</h2>
<table class="standard-table" style="width: auto;"> <tbody> <tr> <td class="header">Attribute</td> <td class="header">Type</td> <td class="header">Description</td> </tr> <tr> <td><code>aboutURL</code></td> <td><code>string</code></td> <td>The URL of the about dialog to display for this add-on. This is passed to {{ domxref("window.openDialog()") }} when presenting the about dialog. If you don't provide an <code>aboutURL</code>, a generic about dialog is displayed. The dialog receives the <code>Addon</code> object representing your add-on as a parameter.</td> </tr> <tr> <td><code>applyBackgroundUpdates</code></td> <td><code>integer</code></td> <td>Indicates whether updates found in the background for this add-on will be applied automatically. See <a href="/en/Addons/Add-on_Manager/AddonManager#Auto_update_values" title="https://developer.mozilla.org/en/Addons/Add-on_Manager/AddonManager#Auto_update_values">auto update values</a>.</td> </tr> <tr> <td><code>contributors</code></td> <td><code>{{ AMInterface("AddonAuthor") }}</code><code>[]</code></td> <td>An array of strings holding the contributors of the add-on.</td> </tr> <tr> <td><code>description</code></td> <td><code>string</code></td> <td>The description of the add-on.</td> </tr> <tr> <td><code>developers</code></td> <td><code>{{ AMInterface("AddonAuthor") }}</code><code>[]</code></td> <td>An array of strings holding the developers of the add-on.</td> </tr> <tr> <td><code>homepageURL</code></td> <td><code>string</code></td> <td>The homepageURL of the add-on.</td> </tr> <tr> <td><code>iconURL</code></td> <td><code>string</code></td> <td>The url of the icon that represents this add-on.</td> </tr> <tr> <td><code>install</code></td> <td><code>{{ AMInterface("AddonInstall") }}</code></td> <td>The {{ AMInterface("AddonInstall") }} that will install this addon. Only available if this addon is in the process of being installed.</td> </tr> <tr> <td><code>installDate</code></td> <td><code>Date</code></td> <td>The Date that the add-on was first installed.</td> </tr> <tr> <td><code>optionsURL</code></td> <td><code>string</code></td> <td>The url of the options dialog to display for this add-on.</td> </tr> <tr> <td><code>pendingUpgrade</code></td> <td><code>{{ AMInterface("Addon") }}</code></td> <td>If a this add-on will be replaced on the next restart this property will hold the new {{ AMInterface("Addon") }} object.</td> </tr> <tr> <td><code>releaseNotesURI</code></td> <td><code>{{ Interface("nsIURI") }}</code></td> <td>A uri for release notes for this version.</td> </tr> <tr> <td><code>screenshots</code></td> <td><code>{{ AMInterface("AddonScreenshot") }}</code><code>[]</code></td> <td>An array of urls of preview images for the add-on.</td> </tr> <tr> <td><code>size</code></td> <td><code>integer</code></td> <td>The size of the add-on's files in bytes. For an add-on that have not yet been downloaded this may be an estimated value.</td> </tr> <tr> <td><code>sourceURI</code></td> <td><code>{{ Interface("nsIURI") }}</code></td> <td>The uri that this add-on was installed from.</td> </tr> <tr> <td><code>syncGUID</code></td> <td>string</td> <td>String GUID to identify the add-on in Sync. The GUID is generated randomly and is made consistent across devices during sync.</td> </tr> <tr> <td><code>translators</code></td> <td><code>{{ AMInterface("AddonAuthor") }}</code><code>[]</code></td> <td>An array of strings holding the translators of the add-on.</td> </tr> <tr> <td><code>updateDate</code></td> <td><code>Date</code></td> <td>The Date that the add-on was most recently updated.</td> </tr> <tr> <td><code>operationsRequiringRestart</code></td> <td><code>integer</code></td> <td>A bitfield holding all of the <a href="/en/Addons/Add-on_Manager/AddonManager#Operations_requiring_restart" title="https://developer.mozilla.org/en/Addons/Add-on_Manager/AddonManager#Operations_requiring_restart">operations</a> that will require a restart to complete for this add-on.</td> </tr> <tr> <td><code>fullDescription</code></td> <td><code>string</code></td> <td> </td> </tr> <tr> <td><code>developerComments</code></td> <td><code>string</code></td> <td> </td> </tr> <tr> <td><code>eula</code></td> <td><code>string</code></td> <td> </td> </tr> <tr> <td><code>icon64URL</code></td> <td><code>string</code></td> <td> </td> </tr> <tr> <td><code>supportURL</code></td> <td><code>string</code></td> <td> </td> </tr> <tr> <td><code>contributionURL</code></td> <td><code>string</code></td> <td> </td> </tr> <tr> <td><code>contributionAmount</code></td> <td><code>string</code></td> <td> </td> </tr> <tr> <td><code>averageRating</code></td> <td><code>number</code></td> <td> </td> </tr> <tr> <td><code>reviewCount</code></td> <td><code>integer</code></td> <td> </td> </tr> <tr> <td><code>reviewURL</code></td> <td><code>string</code></td> <td> </td> </tr> <tr> <td><code>totalDownloads</code></td> <td><code>integer</code></td> <td> </td> </tr> <tr> <td><code>weeklyDownloadss</code></td> <td><code>integer</code></td> <td> </td> </tr> <tr> <td><code>dailyUsers</code></td> <td><code>integer</code></td> <td> </td> </tr> <tr> <td><code>repositoryStatus</code></td> <td><code>integer</code></td> <td> </td> </tr> </tbody>
</table>
<h2>Required Methods</h2>
<h3>isCompatibleWith()</h3>
<p>Tests whether this add-on is known to be compatible with a particular application and platform version.</p>
<pre>void isCompatibleWith(
  in string appVersion,
  in string platformVersion
)</pre>
<h6>Parameters</h6>
<dl> <dt>appVersion</dt> <dd>An application version to test against</dd> <dt>platformVersion</dt> <dd>A platform version to test against</dd>
</dl>
<h3>findUpdates()</h3>
<p>Starts an update check for this add-on. This will perform asynchronously and deliver results to the given listener.</p>
<pre class="eval">void findUpdates(
  in {{ AMInterface("UpdateListener") }} listener,
  in integer reason,
  in string appVersion,
  in string platformVersion
)</pre>
<h6>Parameters</h6>
<dl> <dt>listener</dt> <dd>An {{ AMInterface("UpdateListener") }} for the update process</dd> <dt>reason</dt> <dd>A <a href="/en/Addons/Add-on_Manager/AddonManager#Update_check_reasons" title="en/Addons/Add-on Manager/AddonManager#Update check reasons">reason code</a> for performing the update</dd> <dt>appVersion</dt> <dd>An application version to check for updates for</dd> <dt>platformVersion</dt> <dd>A platform version to check for updates for</dd>
</dl>
<h2>Optional Methods</h2>
<h3>uninstall()</h3>
<p>Uninstalls this add-on. If possible the uninstall will happen immediately otherwise it will wait until the next application restart.</p>
<p>This method must be defined if an add-on has the permission PERM_CAN_UNINSTALL.</p>
<pre>void uninstall(
)</pre>
<h3>cancelUninstall()</h3>
<p>Cancels uninstalling an add-on if it is pending uninstall.</p>
<p>This method must be defined if an add-on has the pendingOperation PENDING_UNINSTALL.</p>
<pre>void cancelUninstall(
)</pre>
<h3>hasResource()</h3>
<p>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.</p>
<pre>boolean hasResource(
  in string path
)</pre>
<h6>Parameters</h6>
<dl> <dt>path</dt> <dd>A "/" separated path for the resource.</dd>
</dl>
<h3>getResourceURI()</h3>
<p>Gets an {{ Interface("nsIURI") }} to the file resource for this add-on.</p>
<pre class="eval">{{ Interface("nsIURI") }} getResourceURI(
  in string path
)</pre>
<h6>Parameters</h6>
<dl> <dt>path</dt> <dd>A "/" separated path for the resource.</dd>
</dl>
Revert to this revision