patch

Summary

Updates an existing component.

Method of

Install object

Syntax

int patch (
   String registryName,
   String xpiSourcePath,
   Object localDirSpec,
   String relativeLocalPath);

int patch (
   String registryName,
   InstallVersion version,
   String xpiSourcePath,
   Object localDirSpec,
   String relativeLocalPath);

int patch (
   String registryName,
   String version,
   String xpiSourcePath,
   Object localDirSpec,
   String relativeLocalPath);

Parameters

The patch method has the following parameters:

registryName

The pathname in the Client Version Registry for the component that is to be patched.This parameter can be an absolute pathname, such as /royalairways/RoyalSW/executable or a relative pathname, such as executable.

Typically, absolute pathnames are only used for shared components, or components that come from another vendor, such as /Microsoft/shared/msvcrt40.dll.

Typically, relative pathnames are relative to the main pathname specified in the initInstall method. This parameter can also be null, in which case the xpiSourcePath parameter is used as a relative pathname.

Note that the registry pathname is not the location of the software on the computer; it is the location of information about the software inside the Client Version Registry.

version

An InstallVersion object or a String of up to four integer values delimited by periods, such as "1.17.1999.1517". For variants or this method without a version argument the value from initInstall will be used.

xpiSourcePath

A string specifying the location of the differences file within the XPI file.

localDirSpec

An object representing the directory in which the subcomponent that is to be patched resides. You create this object by passing a string representing the directory to the getFolder method.

relativeLocalPath

A pathname relative to the localDirSpec parameter that identifies the subcomponent that is to be patched. You must always use forward slashes (/) in this pathname, regardless of the convention of the underlying operating system. If this parameter is blank or NULL, xpiSourcePath is used.

Returns

An integer error code. For a list of possible values, see Return Codes.

Description

The patch method to update an existing component by applying a set of differences between two known versions. The set of differences is in GDIFF format and is created by the NSDiff utility.

A patch can only be applied between two known versions. If the existing version of the file does not match the checksum stored in the GDIFF file, patch returns an error without applying the patch.

After patch applies a patch, it compares a checksum.of the resulting file against a checksum stored in the GDIFF file. If the checksums do not match, the original version of the file is preserved, the patched version of the file is discarded, and an error code is returned.

Any single installation process can apply multiple patches to the same file. If performInstall indicates that a reboot is necessary to complete the installation, patch may not work in subsequent XPInstall processes until the reboot is performed.