Chapter 1 Install

---

Use the Install object to manage the downloading and installation of software with the XPI Installation Manager.

Install Overview

The Install object is used primarily in installation scripts. In all cases, the Install object is implicit--like the window object in regular web page scripts--and needn't be prefixed to the object methods. The following two lines, for example, are equivalent:

 f = getFolder("Program");
f = Install.getFolder("Program");

An installation script is composed of calls to the Install object, and generally takes the following form:

Initialize the installation	call initInstall with the name of the installation and the necessary registry and version information.
Add the files to the installation	Add files to the installation by calling getFolder to get file objects and passing those object refs to addFile as many times as necessary.
Perform installation	Check that the files have been added successfully (e.g., by checking the error Return Codes from many of the main installation methods, and go ahead with the install if everything is in order: performOrCancel(); function performOrCancel() {   if (0 == getLastError())      performInstall();    else      cancelInstall(); }

For complete script examples, see Script Examples.

Method Reference

addDirectory	Unpacks an entire subdirectory.
addFile	Unpacks a single file.
alert	Displays an Alert dialog box with a message and an OK button.
cancelInstall	Aborts the installation of the software.
confirm	Displays a Confirm dialog box with the specified message and OK and Cancel buttons.
deleteRegisteredFile	Deletes the specified file and its entry in the Client Version Registry.
execute	Extracts a file from the XPI file to a temporary location and schedules it for later execution.
gestalt	Retrieves information about the operating environment. (Mac OS only)
getComponentFolder	Returns an object representing the directory in which a component is installed.
getFolder	Returns an object representing a directory, for use with the addFile method.
getLastError	Returns the most recent non-zero error code.
getWinProfile	Constructs an object for working with a Windows .ini file.
getWinRegistry	Constructs an object for working with the Windows Registry.
initInstall	Initializes installation for the given software and version.
loadResources	Returns an object whose properties are localized strings loaded from the specified property file.
logComment	Add a comment line to the install log.
patch	Applies a set of differences between two versions.
performInstall	Finalizes the installation of the software.
refreshPlugins	Refreshes the list of plug-ins registered for the browser.
registerChrome	Registers chrome with the chrome registry.
resetError	Resets a saved error code to zero.
setPackageFolder	Sets the default package folder that is saved with the root node.

Property Reference

arguments	args can be passed in through the triggering APIs by attaching a ? and then the rg string to the xpi URL: (e.g., startSoftwareUpdate("http://webserver/argstest.xpi?ARGUMENT_STRING will result in the value of Install.arguments being ARGUMENT_STRING ). Note, spaces in the arg string are legal. Everything after the question mark uis treated as one string which becomes the Install.arguments property.
archive	Full local path of the archive after it is downloaded to the platform specific temp folder. (e.g. C:\TEMP\argstest.xpi)
url	The fully qualified URL of the xpi (file URL, http URL, ftp URL, etc.)( e.g. http://dolfin/sgehani/zzz/ip.xpi ). Note, even if triggered using relative URLs this will show the full URL (after qualification).