The ApplyPatchFile function applies a patch file against the specified file on the target system, creating an updated version of the file.

BOOL ApplyPatchFile(
	LPCTSTR lpszPatchFile,		// name of patch file
	DWORD dwPatchOptions,		// patch options
	DWORD dwReserved,		// reserved
	LPCTSTR lpszPassword,		// password
	LPCTSTR lpszOldFile,		// name of old file
	LPCTSTR lpszNewFile,		// name of new file
	LPPATCHSTATUSPROC lpfnCallback,		// pointer to callback function
	LPARAM lParam		// callback function parameter
);

Parameters

lpszPatchFile

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

 

dwPatchOptions

[in] Specifies a set of options which are used during the patch apply process. If this parameter is zero, the options that were specified when the patch file was created will be used.

 

One or more of the following values may be used:

Value	Description
PATCH_OPTION_FIND_FILE	If the reference file cannot be found on the target system, attempt to locate it using the standard Windows pathing rules. The current directory, system directory and the directories in the PATH environment variable are searched in that order.
PATCH_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.
PATCH_OPTION_NOUPDATE	Do not modify the target file on the local system. This option can be used to test the patch file to ensure it can be successfully applied.
PATCH_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.
PATCH_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.
PATCH_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.
PATCH_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.
PATCH_OPTION_IGNORE_ATTRIBUTES	Ignore the updated file attributes when the patch is applied on the target system and use default attributes instead.
PATCH_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.
PATCH_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.

dwReserved

[in] Reserved; must be zero.

 

lpszPassword

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

 

lpszOldFile

[in] A pointer to a null-terminated string which specifies the name of the original version of the file on the target system.

 

lpszNewFile

[in] A pointer to a null-terminated string which specifies the name of the updated file. If this file already exists, it will be overwritten. If this parameter is NULL or points to an empty string, the original file will be replaced with the updated version.

 

lpfnCallback

[in] Specifies the address of a callback function of type LPPATCHSTATUSPROC that is called each time another portion of the patch file has been applied. This parameter can be NULL.

 

For more information on the progress callback function, see PatchStatusProc.

 

lParam

[in] A 32-bit user-defined parameter that is passed through the callback function. If no callback function has been specified, this parameter should be zero.

Return Values

If the ApplyPatchFile 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

To preseve a copy of the original file, use the PATCH_OPTION_BACKUP_FILE option, which will create a backup copy of the file before applying the patch. The backup file will have the same name as the original, except that the extension will be replaced with a three digit number, starting at zero. This allows multiple backup copies of the file to be created, with the highest number specifying the most recent copy.

The original file must be found in the exact location specified. If there is a possibility that the file has been moved by the user (for example, into another subdirectory), use the PATCH_OPTION_FIND_FILE option. This will cause the function to search for the file in any subdirectories, as well as using the standard Windows pathing rules to attempt to locate the file.

If neither PATCH_OPTION_COMPARE_FILETIME nor PATCH_OPTION_IGNORE_FILETIME is specified, then PATCH_OPTION_COMPARE_FILETIME is the default. If both PATCH_OPTION_COMPARE_FILETIME and PATCH_OPTION_IGNORE_FILETIME are specified, then PATCH_OPTION_IGNORE_FILETIME takes precedence.

If neither PATCH_OPTION_COMPARE_VERSION nor PATCH_OPTION_IGNORE_VERSION is specified, then PATCH_OPTION_COMPARE_VERSION is the default. If both PATCH_OPTION_COMPARE_VERSION and PATCH_OPTION_IGNORE_VERSION are specified, then PATCH_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

ApplyPackage, CreatePatchFile, GetPatchFileInformation