The CPackage::Apply function applies the specified package on the target system.

BOOL Apply(
	LPCTSTR lpszPackageFile,		// name of package file
	DWORD dwOptionFlags,		// package options
	LPDWORD lpdwStatusFlags,		// apply status flags
	LPCTSTR lpszPassword,		// password
	LPCTSTR lpszInstallPath,		// installation path
	LPCTSTR lpszUndoFile,		// name of package undo file
);

Parameters

lpszPackageFile

[in] A pointer to a null-terminated string which specifies the name of the package file that is to be applied.

 

dwOptionFlags

[in] Specifies the options to use when applying the package file. If no options are provided, the options used when creating the package will be used.

 

The following values may be specified:

Value	Description
PACKAGE_OPTION_FIND_FILE	When the patch package is applied to the target system, search for files using the standard Windows pathing rules.
PACKAGE_OPTION_REGISTER_COMPONENTS	This option specifies that any self-registering COM libraries and/or ActiveX controls that are included with the package will be automatically registered after the package has been applied.
PACKAGE_OPTION_OVERWRITE	When the patch package is applied to the target system, overwrite all files even if the file is not expected to exist. This option must be specified if one or more of the target files will have the read-only attribute set, otherwise the application process will fail with an error.
PACKAGE_OPTION_NOUPDATE	Do not modify any files on the local system. This option can be used to test a package to ensure that it can be successfully applied on the local system.
PACKAGE_OPTION_IGNORE_MISSING	When the patch package is applied to the target system, ignore any missing files.
PACKAGE_OPTION_IGNORE_EXISTING	When the patch package is applied to the target system, ignore any existing files that are not expected to exist. This option is effectively the opposite of PACKAGE_OPTION_OVERWRITE, and ensures that the existing file is not modified.
PACKAGE_OPTION_BACKUP_FILE	Create a backup of the file on the target system before applying the patch. If this flag is not specified, the file is modified in-place without any backup file being created.
PACKAGE_OPTION_COMPARE_FILETIME	Compare the time that the target file was last modified against that of the reference file. If the target file has a later modification time than the reference file at the time the patch was created, the patch application will fail with the error AP_ERROR_NEWER_FILETIME. In effect this ensures that the updated file must always have a later modification time than the reference file.
PACKAGE_OPTION_COMPARE_VERSION	Compare the version of the target file against that of the reference file. If the target file has a later version than the reference file at the time the patch was created, the patch application will fail with the error AP_ERROR_NEWER_VERSION. In effect this ensures that the updated file must always be a later version than the reference file.
PACKAGE_OPTION_IGNORE_FILETIME	Ignore any differences between the file modification times of the file on the target system and those of the reference file at the time that the patch was created.
PACKAGE_OPTION_IGNORE_VERSION	Ignore any differences between the version of the file on the target system and the version of the reference file at the time that the patch was created.
PACKAGE_OPTION_IGNORE_ATTRIBUTES	Ignore the updated file attributes when the patch is applied on the target system and use default attributes instead.
PACKAGE_OPTION_IGNORE_READONLY	Ignore the read-only file attribute when applying the patch. If the updated file has this attribute set, it will be cleared.
PACKAGE_OPTION_IGNORE_SIGNATURE	Ignore any digital signature that may be present. If the updated file has been digitally signed using AuthentiCode, the signature will be authenticated at the time that the patch is applied. If this flag is specified, no attempt is made to authenticate the signature. This flag has no effect on files that are not digitally signed.
PACKAGE_OPTION_IGNORE_MODIFIED	Ignore any files in the package which have been modified on the local system. This option should be used with caution because it specifically prevents the function from returning an error if a modified file is found.

lpdwStatusFlags

[out] A pointer to an unsigned long integer which will contain the status of the current package application process. This parameter may be NULL if the additional status  information is not required. If the package has been applied successfully, this value will be non-zero and may be one or more of the following values:

 

Value	Description
APPLY_STATUS_COMPLETED	The package application process has completed successfully.
APPLY_STATUS_DELAYED	The package application completed, however one or more files were in use. The system should be restarted to complete the update process.

lpszPassword

[in] A pointer to a null-terminated string which specifies the password that was used to secure the package. A package created with a password cannot be applied unless it matches the password that was provided to the CPackage::Create function. Note that the password is case sensitive. If no password was specified, this parameter may be NULL or point to an empty string.

 

lpszInstallPath

[in] A pointer to a null-terminated string which specifies the location on the target system where the files will be created, modified or deleted. This parameter may be NULL, in which case the files will be installed in the default installation directory on the target system.

 

lpszUndoFile

[in] A pointer to a null-terminated string which specifies the name of a file which will contain the instructions and data for reversing the application of the package file. This parameter may be NULL or point to an empty string, in which case no file is created.

Return Values

If the CPackage::Apply function succeeds, it will return a non-zero value.

If the function fails, it will return a value of zero. To get extended error information, call GetLastError.

Remarks

Because self-registering COM libraries and ActiveX controls can potentially be used to execute arbitrary code on the target system, the Apply function will not register any components included in the package. The option PACKAGE_OPTION_REGISTER_COMPONENTS must be specified if you wish to automatically register the components after the package has been applied.

A file is "not expected to exist" if the application instructions within the package indicate that the file is to be created on the target system.

If neither PACKAGE_OPTION_COMPARE_FILETIME nor PACKAGE_OPTION_IGNORE_FILETIME is specified, then PACKAGE_OPTION_COMPARE_FILETIME is the default. If both PACKAGE_OPTION_COMPARE_FILETIME and PACKAGE_OPTION_IGNORE_FILETIME are specified, then PACKAGE_OPTION_IGNORE_FILETIME takes precedence.

If neither PACKAGE_OPTION_COMPARE_VERSION nor PACKAGE_OPTION_IGNORE_VERSION is specified, then PACKAGE_OPTION_COMPARE_VERSION is the default. If both PACKAGE_OPTION_COMPARE_VERSION and PACKAGE_OPTION_IGNORE_VERSION are specified, then PACKAGE_OPTION_IGNORE_VERSION takes precedence.

Requirements

Windows NT/2000/XP: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later.
Header: Include apatch.h.
Library: Use apatch32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000/XP.

See Also

CPatchFile::Apply, CPackage::Create, CPackage::UndoApply, CPackage::Update