The CreatePackage function creates a new patch package or overwrites an existing package file.

HPACKAGE WINAPI CreatePackage(
	LPCTSTR lpszPackageFile,		// name of package file
	DWORD dwOptionFlags,		// package options
	DWORD dwUpdateFlags,		// update options
	DWORD dwTargetPlatform,		// target platforms
	LPCTSTR lpszPassword,		// password
	LPCTSTR lpszReferencePath,		// old file specification
	LPCTSTR lpszUpdatePath,		// new file specification
	LPCTSTR lpszInstallPath,		// installation directory
	LPCTSTR lpszExcludeMask,		// file exclude mask
	LPPATCHSTATUSPROC lpfnCallback,		// pointer to callback function
	LPARAM lParam		// callback function parameter
);

Parameters

lpszPackageFile

[in] A pointer to a null-terminated string which specifies the name of the package to create or overwrite.

 

dwOptionFlags

[in] Specifies the options to use when creating the package file.

 

The following values may be used:

Value	Description
PACKAGE_OPTION_MULTIPLE_VERSIONS	Multiple versions of the same file may be included in the package. If this option is not specified, a file with the same name will overwrite a previous file in the package.
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_IGNORE_MISSING	When the patch package is applied to the target system, ignore any missing files.
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_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.

dwUpdateFlags

[in] Specifies the options which determine how updated files are added to the patch package.

 

The following values may be used:

 

Value	Description
PACKAGE_UPDATE_RECURSIVE	The reference and update directories should be recursively scanned for new, modified and deleted files. If this update option is not used, only those files in the specified directory will be included in the package.
PACKAGE_UPDATE_PARTIAL	This is a partial update, therefore files missing from the new file directory should not be marked for removal from the target system.
PACKAGE_UPDATE_ALWAYS_REPLACE	Always replace changed files instead of creating a patch. The file on the target system will always be overwritten, regardless of its previous version.

dwTargetPlatform

[in] Specifies the platforms that the files may be applied to.

 

This may be one of the following values:

 

Value	Description
PACKAGE_FILE_PLATFORM_DEFAULT	The files may be applied on all Windows platforms. This is the same as specifying a value of PACKAGE_FILE_PLATFORM_WINDOWS.
PACKAGE_FILE_PLATFORM_WIN95	The files may be applied to a system running Windows 95.
PACKAGE_FILE_PLATFORM_WIN98	The files may be applied to a system running Windows 98 or Windows 98 SE.
PACKAGE_FILE_PLATFORM_WINME	The files may be applied to a system running Windows ME.
PACKAGE_FILE_PLATFORM_WINNT40	The files may be applied to a system running Windows NT 4.0.
PACKAGE_FILE_PLATFORM_WIN2000	The files may be applied to a system running Windows 2000.
PACKAGE_FILE_PLATFORM_WINXP	The files may be applied to a system running Windows XP.
PACKAGE_FILE_PLATFORM_WIN2003	The files may be applied to a system running Windows Server 2003.

In addition to the above platform-specific values, there are predefined values which specify platform groups:

 

Value	Description
PACKAGE_FILE_PLATFORM_WIN32	The files may be applied to any 32-bit version of the Windows operating system.
PACKAGE_FILE_PLATFORM_WIN9X	The files may be applied to any system running Windows 95, Windows 98 or Windows ME. They will not be applied on a system running Windows NT, Windows 2000 or Windows XP.
PACKAGE_FILE_PLATFORM_WINNT	The files may be applied to any system running Windows NT, Windows 2000 or Windows XP. They will not be applied on a system running Windows 95, Windows 98 or Windows ME.
PACKAGE_FILE_PLATFORM_WINDOWS	The files may be applied to any system running any version of Microsoft Windows.

lpszPassword

[in] A pointer to a null-terminated string which specifies a password that is used to secure the package. A package created with a password cannot be opened or subsequently modified without providing the password.

 

lpszReferencePath

[in] A pointer to a null-terminated string which specifies the files or directories that contain the original version of the files to be updated. This may specify a directory, in which case all files in the directory are scanned, or it may be a file name. The name may include wildcards to match one or more files. If the PACKAGE_FLAG_RECURSIVE option is specified, all subdirectories under the specified directory will also be scanned. If this parameter is NULL, the files specified by the lpszUpdatePath parameter will be added to the package and created on the target system.

 

lpszUpdatePath

[in] A pointer to a null-terminated string which specifies the files or directories that contain the updated version of the files. This may specify a directory, in which case all files in the directory are scanned, or it may be a file name. The name may include wildcards to match one or more files. If the PACKAGE_FLAG_RECURSIVE option is specified, all subdirectories under the specified directory will also be scanned. If this parameter is NULL, the files specified by the lpszReferencePath parameter willl be removed from the target system.

 

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.

 

lpszExcludeMask

[in] A pointer to a null-terminated string which specifies one or more file names (typically with wildcards) that are to be excluded from the package. Multiple files may be specified by separating them with a semi-colon.

 

lpfnCallback

[in] Specifies the address of a callback function of type LPPATCHSTATUSPROC that is called each time a change is made to the package file. 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 function succeeds, the return value is an open handle to the specified package file.

If the function fails, the return value is INVALID_PACKAGE_HANDLE. To get extended error information, call GetLastError.

Remarks

Use the ClosePackage function to close the package file and release the memory allocated for the package.

The handle returned by this function is not a handle to a Windows object and cannot be used with functions such as ReadFile and WriteFile.

An application method will be associated with each file that is added to the package. The possible application methods are: Create, Replace, Modify, and Delete. An application method for a given file is determined by this function through comparison of the files referred to by the lpszReferencePath and lpszUpdatePath specifications.

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

ApplyPackage, CreatePatchFile, ClosePackage, UpdatePackage