ActivePatch Data Structures - PACKAGE_FILE

PACKAGE_FILE_INFORMATION

The PACKAGE_FILE_INFORMATION structure contains information about a package file, including details about the reference or update files that were used to create the patch. This structure is used with the GetPackageFileInformation function.

typedef struct _PACKAGE_FILE_INFORMATION
{
      DWORD                 cbStructure; 
      WORD                  wApplyMethod; 
      WORD                  wFileType; 
      WORD                  wFileFlags; 
      WORD                  wFileCompression; 
      DWORD                 dwFileSize; 
      DWORD                 dwFileAttributes; 
      DWORD                 dwFileChecksum; 
      DWORD                 dwFileVersionMS; 
      DWORD                 dwFileVersionLS; 
      DWORD                 dwFilePlatformId; 
      FILETIME              timeFileCreated; 
      FILETIME              timeFileAccessed; 
      FILETIME              timeFileModified; 
      TCHAR                 szInstallPath[MAX_PATH]; 
      TCHAR                 szFileName[MAX_PATH]; 
} PACKAGE_FILE_INFORMATION;

Members

cbStructure

Specifies the size, in bytes, of this data structure. Set this member to sizeof(PACKAGE_FILE_INFORMATION) before calling the GetPackageFileInformation function.

wApplyMethod

Specifies how the file will be applied on the target system.

This may be one of the following values:

Value Description

PACKAGE_APPLY_CREATE The file will be created on the target system. If a file with the same name already exists, the file will not be overwritten. If the package option PACKAGE_OPTION_IGNORE_EXISTING has not been specified, an error will be returned during the apply process.

PACKAGE_APPLY_REPLACE The file will be created on the target system. If a file with the same name already exists, the file will be overwritten.

PACKAGE_APPLY_MODIFY The file will be modified on the target system. If the package option PACKAGE_OPTION_IGNORE_MISSING has not been specified, an error will be returned during the apply process.

PACKAGE_APPLY_REMOVE The file will be removed from the target system. If the package option PACKAGE_OPTION_IGNORE_MISSING has not been specified, an error will be returned during the apply process.

wFileType

Specifies the type of file.

This may be one of the following values:

Value Description

PACKAGE_FILE_TYPE_NORMAL This is a normal file (not a patch file) which has been stored in the package.

PACKAGE_FILE_TYPE_PATCH This is a patch file which has been stored in the package. The values in this structure are for the reference file (the file being patched) not the patch file itself.

wFileFlags

Specifies one or more flags which may be set for the file.

The following values may used:

Value Description

PACKAGE_FILE_FLAG_SHARED The file is shared and may be locked on the target system. This is typically specified for shared components and libraries which may be in use at the time that the patch package is applied.

PACKAGE_FILE_FLAG_REGISTER The file is a self-registering COM object and should be registered when the file is installed on the local system. If this flag is set for a PACKAGE_FILE_TYPE_PATCH file, the patch is applied and then the file is registered.

PACKAGE_FILE_FLAG_REPLACE When this file is extracted from the package, it should replace any existing file with the same name. If this flag is not set and the file already exists, an error will be returned when it is extracted.

PACKAGE_FILE_FLAG_VERSIONINFO The file has version information available. The dwVersionMS and dwVersionLS members will contain the version numbers.

PACKAGE_FILE_FLAG_SIGNED The file has been digitally signed using Microsoft's AuthentiCode.

PACKAGE_FILE_FLAG_COMPRESSED The file has been compressed when added to the package. The file will be automatically expanded when extracted. Note that this flag will only be set for PACKAGE_FILE_TYPE_NORMAL files.

wFileCompression

Specifies the percentage compression ratio for the file, with a value in a range of 0 to 100.

dwFileSize

Specifies the size of the file. If the file type is PACKAGE_FILE_TYPE_PATCH then this value specifies the size of the original reference file, not the size of the patch file itself.

dwFileAttributes

Specifies the attributes of the file.

The attributes may be one or more of the following values:

Attribute Meaning

FILE_ATTRIBUTE_ARCHIVE The file or directory is an archive file or directory. Applications use this attribute to mark files for backup or removal.

FILE_ATTRIBUTE_HIDDEN The file or directory is hidden. It is not included in an ordinary directory listing.

FILE_ATTRIBUTE_NORMAL The file or directory has no other attributes set. This attribute is valid only if used alone.

FILE_ATTRIBUTE_READONLY The file or directory is read-only. Applications can read the file but cannot write to it or delete it.

FILE_ATTRIBUTE_SYSTEM The file or directory is part of, or is used exclusively by, the operating system.

dwFileChecksum

Specifies a 32-bit CRC (cyclic redundancy checksum) value which is derived from the contents of the file. This value can be used to uniquely identify a file.

dwFileVersionMS

Specifies the most significant portion of the file version at the time that the patch was created. If there was no version information available, this value will be zero.

dwFileVersionLS

Specifies the least significant portion of the file version at the time that the patch was created. If there was no version information available, this value will be zero.

dwFilePlatformId

Specifies the platform that this file may be installed on.

This may be one of the following values:

Value Description

PACKAGE_FILE_PLATFORM_WIN95 The file may be applied to a system running Windows 95.

PACKAGE_FILE_PLATFORM_WIN98 The file may be applied to a system running Windows 98 or Windows 98 SE.

PACKAGE_FILE_PLATFORM_WINME The file may be applied to a system running Windows ME.

PACKAGE_FILE_PLATFORM_WINNT40 The file may be applied to a system running Windows NT 4.0.

PACKAGE_FILE_PLATFORM_WIN2000 The file may be applied to a system running Windows 2000.

PACKAGE_FILE_PLATFORM_WINXP The file 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 file may be applied to any 32-bit version of the Windows operating system.

PACKAGE_FILE_PLATFORM_WIN9X The file may be applied to any system running Windows 95, Windows 98 or Windows ME. The file will not be applied on a system running Windows NT, Windows 2000 or Windows XP.

PACKAGE_FILE_PLATFORM_WINNT The file may be applied to any system running Windows NT, Windows 2000 or Windows XP. The file 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.

timeFileCreated

A FILETIME structure which contains the date and time that the file was created. The time value is returned in UCT and should be converted to local time when displayed. Note that not all file systems record the creation time for a file. In this case, the FILETIME structure members will have zero values.

timeFileAccessed

A FILETIME structure which contains the date and time that the file was last accessed. The time value is returned in UCT and should be converted to local time when displayed. Note that not all file systems record the last access time for a file. In this case, the FILETIME structure members will have zero values.

timeFileModified

A FILETIME structure which contains the date and time that the file was last modified. The time value is returned in UCT and should be converted to local time when displayed.

szInstallPath

A null-terminated character array which specifies the name of the directory that the file will be installed in. This value may specify a logical folder name such as [WINSYSDIR] or a local directory specification. If this member is an empty string, then the file is applied using the default installation path.

szFileName

A null-terminated character array which specifies the name of the file. Note that the file name may also include a relative path specification (such as "data/product.dat"), in which case it will be installed in a subdirectory under the installation directory.

Remarks

Version information is only available for 32-bit executables, dynamic link libraries, ActiveX controls and other Windows PE image modules. The high word of the most significant version number is typically considered to be the major version, while the low word is the minor version. The least significant version number is commonly the build number. For example, an executable with a dwFileVersionMS value of 65568 (10020h) and a dwFileVersionLS value of 1225 (4C9h) would be considered to be Version 1.20 Build 1225.

Not all file systems can record creation and last access time and not all file systems record them in the same manner. For example, on Windows NT FAT, create time has a resolution of 10 milliseconds, write time has a resolution of 2 seconds, and access time has a resolution of 1 day (the access date). On NTFS, access time has a resolution of 1 hour.

To convert the FILETIME values to a more usable format, use the FileTimeToSystemTime function. To compare two file times, use the CompareFileTime function. Both functions are part of the standard Windows API.

It is possible for a file name to include an absolute path specification, although this is not recommended. If the file name does include an absolute path, this takes precedence over the installation path specified for the file.

Requirements

Windows NT/2000/XP: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later.
Header: Declared in apatch.h.

See Also

CreatePackage, ExtractPackageFile, GetPackageFileInformation, StorePackageFile, UpdatePackage