nsIInstallLocation

Interface representing a location where extensions, themes and so on are installed.
1.0
28
Introduced
Gecko 1.8
Obsolete
Gecko 2.0
Inherits from: nsISupports Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

Note: While this API still works, Firefox 4 no longer extracts XPIs by default, so this will now point to the XPI file instead of to the directory. Any nsIFile operations that assume a directory and plain files will fail in Firefox 4, unless you specify <em:unpack>.

You can get the install location of a particular add-on using nsIExtensionManager interface:

var il = Components.classes["@mozilla.org/extensions/manager;1"]
                   .getService(Components.interfaces.nsIExtensionManager)
                   .getInstallLocation("add-on id")

Method overview

AString getIDForLocation(in nsIFile file);
nsIFile getItemFile(in AString id, in AString path);
nsIFile getItemLocation(in AString id);
nsIFile getStageFile(in AString id);
boolean itemIsManagedIndependently(in AString id);
void removeFile(in nsIFile file);
nsIFile stageFile(in nsIFile file, in AString id);

Attributes

Attribute Type Description
canAccess boolean Whether or not the user can write to the Install Location with the current access privileges. This is different from restricted because it's not whether or not the location *might* be restricted, it's whether or not it actually *is* restricted right now. Read only.
itemLocations nsIDirectoryEnumerator

An enumeration of nsIFiles for:

  • Locations that contain items
  • Potential dropped-in XPIs
Note: This enumeration resolves Text Links to the directories they refer to.
Read only.
location nsIFile

The file system location where items live. Items can be dropped in at this location. Can be null for Install Locations that don't have a file system presence.

Note: This is a clone of the actual location which the caller can modify freely.
Read only.
name AString The string identifier of this Install Location. Read only.
priority long The priority level of this Install Location in loading. Read only.
restricted boolean Whether or not this Install Location is on an area of the file system that could be restricted on a restricted-access account, regardless of whether or not the location is restricted with the current user privileges. Read only.

Constants

Constants representing priority of some default Install Locations. You should not use the exact values here, you should offset from these values each time you create a new Install Location. Offsetting can be brittle but you should know what Install Locations are being defined for your own application.

Constant Value Description
PRIORITY_APP_PROFILE 0  
PRIORITY_APP_SYSTEM_USER 10  
PRIORITY_XRE_SYSTEM_USER 100  
PRIORITY_APP_SYSTEM_GLOBAL 1000  
PRIORITY_XRE_SYSTEM_GLOBAL 10000  

Methods

getIDForLocation()

Retrieves the GUID for an item at the specified location.

Note: This function makes no promises about whether or not this path is actually maintained by this Install Location.

AString getIDForLocation(
  in nsIFile file
);
Parameters
file
The location where an item might live.
Return value

The ID for an item that might live at the location specified.

getItemFile()

Gets a nsIFile object for a file within an item's directory structure.

nsIFile getItemFile(
  in AString id,
  in AString path
);
Parameters
id
The GUID of the item.
path
The path to the file beneath an Extension's directory.
Return value

A file object at the requested location. The file does not necessarily have to exist.

getItemLocation()

Gets the directory that contains an item.

nsIFile getItemLocation(
  in AString id
);
Parameters
id
The GUID of the item.
Return value

The location of the item.

Requires Gecko 1.9 (Firefox 3)

getStageFile()

Returns the most recently staged package (for example the last XPI or JAR in a directory) for an item and removes items that do not qualify.

nsIFile getStageFile(
  in AString id
);
Parameters
id
The ID of the staged package.
Return value

An nsIFile if the package exists otherwise null.

itemIsManagedIndependently()

Determines whether or not an item's resources are managed by the Extension System or by some other user or process. For example, items linked to by text links are managed by the user, and items linked to from Registry Install Locations are usually managed by other applications or installers.

boolean itemIsManagedIndependently(
  in AString id
);
Parameters
id
The GUID of the item.
Return value

true if the item's resources are managed independently of the Extension System, false otherwise.

Requires Gecko 1.9 (Firefox 3)

removeFile()

Removes a file from the stage. This cleans up the stage if there is nothing else left after the remove operation.

void removeFile(
  in nsIFile file
);
Parameters
file
The file to remove.

Requires Gecko 1.9 (Firefox 3)

stageFile()

Stages the specified file by copying it to some location from where it can be retrieved later to complete installation.

nsIFile stageFile(
  in nsIFile file,
  in AString id
);
Parameters
file
The file to stage.
id
The GUID of the item the file represents.
Return value

The staged file.

Document Tags and Contributors

Tags: 
 Contributors to this page: Sheppy, trevorh, BenB, Smi, Nickolay, JSlim180
 Last updated by: Sheppy,