Microsoft Corporation
June 2005
Summary: Learn about the Delta Compression technology that leverages the similarities of two files, and can yield significantly smaller compressed files than those produced by other methods. It has been used to deploy software updates for Microsoft Windows. (34 printed pages)
Contents
Introduction
Overview of Delta Compression Technology
Note on Terminology
Delta Compression Effectiveness
Obtaining the Files
Dependencies
API Description
Practical Usage
White Papers on Delta Compression
Glossary
Introduction
Delta compression is a lossless differential compression technology developed by Microsoft and primarily used for software updates. Differential compression leverages the similarities of two files, which can yield significantly smaller compressed files than that produced by other compression methods.
Overview of Delta Compression Technology
In a conventional data compression system, the compressor accepts one file and produces a more compact representation of that file. The decompressor performs the inverse function, accepting the compact form and reconstructing the original file.
Figure 1 illustrates this process. The compressor accepts some target data F' and produces a compressed representation C(F'). Later, the decompressor accepts C(F') and reconstructs the target data F'.
.gif)
Figure 1. Conventional data compression
The Delta Compression system also uses a compressor, but this compressor accepts two inputs. One is the target file to be compressed, and the other is a reference or basis file. As in conventional compression, the delta creator produces a more compact representation of the target file. The compact representation or delta may include references to similar data found in the basis file. The delta decompressor, or applier, accepts the delta along with the basis file, and reconstructs the target file.
Figure 2 illustrates the Delta Compression process. The delta creator accepts target data F' along with basis F, and produces a compressed representation ÄF-F'. Later, the delta applier accepts the delta ÄF-F' along with the same basis F, and reconstructs the target data F'.
.gif)
Figure 2. Delta compression
Note on Terminology
The terms basis, target, and delta are used throughout this document. Earlier development used the terms old file (for basis), new file (for target), and patch (for delta). Although the function parameters of the API reflect the earlier usage, the descriptive text in this document uses the new terminology for consistency with ongoing development. Also, the term "Apply" is used to describe the decompression process, but it should be noted that "Apply" never means to modify an existing file; this decompression always produces a completely new copy of the original target.
Delta Compression Effectiveness
The delta will be small when files F and F' are similar. One common scenario is when the basis is just an older version of the target file. The difference between these two versions might be small (just the updates/fixes that have been made in the most recent version) and therefore the delta will be small.
However, Delta Compression is not limited to creating deltas between different versions of the same file. The create process takes two files as input regardless of their content. The size of the delta is affected by the similarity (or lack thereof) between these two files.
Data appearing in the target that has no similar data in the basis still gets compressed. In the worst-case scenario, where the basis and target have nothing in common, the delta is just like a compressed form of the target.
The Delta Compression API offers special handling for certain types of executable files (PE files, such as EXE or DLL files.) In particular, executables designed to run on the 32-bit Intel i386 family get special treatment. When the basis and target files are similar executables, this feature can reduce the size of the delta significantly—typically 50-70% further.
To get the maximum benefit from this feature, symbol files from the LINK process can be supplied during delta creation. This will help the creation process recognize the nature of the changes between the files. Richer symbol info, such as private symbols, will help make smaller deltas. Figure 3 illustrates this process.
.gif)
Figure 3. Delta compression using symbol files
None of the symbol data is passed in the delta, and the symbol files are not needed during the delta apply process.
See Optional Data for Delta Create for more information on how symbols can be provided.
Obtaining the Files
The Delta Compression API includes the following files:
- mspatcha.dll: Dynamic link library for applying deltas. This library is shipped with Windows XP, Windows 2000, and Windows Server 2003. It can be found in the System32 directory.
- mspatchc.dll: Dynamic-link library for creating deltas. This library is part of the Windows Installer SDK.
- patchapi.h: Header file that defines the API functions, structures, and constants. This header is part of the Windows Installer SDK.
To download the Windows Installer SDK
- Go to the Platform SDK Installer page:
- At the bottom of the page, select the download appropriate for your CPU type.
- When prompted, choose Run.
For a default installation, the SDK is installed in:
C:\Program Files\Microsoft Platform SDK
If desired, the installation may be customized to include only the Microsoft Windows Installer SDK.
The paths to the files are:
- \Samples\sysmgmt\msi\patching\mspatchc.dll
- \include\patchapi.h
Dependencies
- mspatcha.dll
- mspatchc.dll
- kernel32.dll
- imagehlp.dll
API Description
This section describes the API, and is split into the following sections:
Function Descriptions
The following table summarizes the API by grouping similar functions together. Each group has three variants of each function:
- To support Unicode file paths (the function name has a W suffix).
- To support ANSI file paths (the function name has an A suffix).
- To support files accessed by handles (the function name has a ByHandles suffix).
Note: The header file patchapi.h conforms to the usual convention where the function names are defined according to whether UNICODE is defined or not. For example, if UNICODE is defined, CreatePatchFile is defined as CreatePatchFileW.
Table 1. Function Groups for API
File Name Arguments
Many of the API functions include arguments that are file names, such as:
- FileName
- NewFileName
- OldFileName
- PatchFileName
- PatchHeaderFileName
These arguments can be specified as a simple file name, a relative path and file name, or an absolute path. A simple file name or a relative path and file name are assumed to be relative to the current directory. The supplied file names are passed as-is to underlying Win32 APIs, e.g., CreateFile.
Compressing a Target Without a Basis File
If a Delta Create function is called and the basis file is specified as NULL (file name string pointer for functions that designate files by paths) or INVALID_HANDLE_VALUE (handle for functions that designate files by handles), the output will be a compressed target file that is not actually a delta. However, for functions that support multiple basis files, NULL or INVALID_HANDLE_VALUE can be supplied only when a single basis file is used (OldFileCount = 1). See Creating Deltas from Multiple Basis Files.
Progress Callback
The following functions provide progress reporting through a progress callback (application-supplied function).
A callback specified when calling the above functions must conform to the following type definition from patchapi.h:
typedef BOOL (CALLBACK PATCH_PROGRESS_CALLBACK)(
PVOID CallbackContext,
ULONG CurrentPosition,
ULONG MaximumPosition
);
Table 2. Progress callback parameter descriptions
| Parameter | Description |
| CallbackContext | Pointer to application-defined callback context. |
| CurrentPosition | Represents the amount of processing currently completed. |
| MaximumPosition | Represents the total amount of processing required. |
The callback function returns a BOOL. Returning TRUE allows processing to continue. Returning FALSE will cause the API to abort.
Optional Data for Delta Create
The following functions accept parameters for optional data of type PATCH_OPTION_DATA.
Note: The GetFilePatchSignature functions also include a parameter OptionData (declared as PVOID) that is actually a pointer to PATCH_OPTION_DATA, but in the GetFilePatchSignature functions, the OptionData parameter is ignored.
The PATCH_OPTION_DATA structure is defined in patchapi.h:
typedef struct _PATCH_OPTION_DATA {
ULONG SizeOfThisStruct;
ULONG SymbolOptionFlags;
LPCSTR NewFileSymbolPath;
LPCSTR *OldFileSymbolPathArray;
ULONG ExtendedOptionFlags;
PPATCH_SYMLOAD_CALLBACK SymLoadCallback;
PVOID SymLoadContext;
} PATCH_OPTION_DATA, *PPATCH_OPTION_DATA;
Table 3. PATCH_OPTION_DATA member descriptions
| Member | Description |
| SizeOfThisStruct | The size of this structure, in bytes, for validation. |
| SymbolOptionFlags | PATCH_SYMBOL_nnn flags (see Symbol Option Flags). |
| NewFileSymbolPath | The path to the directory containing symbol files (.pdb) for the target. Always ANSI. Never Unicode. |
| OldFileSymbolPathArray | Pointer to an array containing the paths to directories containing symbol files (.pdb) for the basis file. |
| ExtendedOptionFlags | Reserved. |
| SymLoadCallback | Pointer to application-defined symbol callback function. |
| SymLoadContext | Pointer to application-defined symbol context. |
PATCH_OPTION_DATA contains LPCSTR paths, and no LPCWSTR (Unicode) path argument is available, even when used with one of the Unicode APIs such as CreatePatchFileW. This is because the underlying system services for symbol file handling (imagehlp.dll) only support ANSI file and path names.
One of the members of PATCH_OPTION_DATA is the type PATCH_SYMLOAD_CALLBACK. PATCH_SYMLOAD_CALLBACK allows imagehlp.dll to provide a callback to notify the caller of information about the symbols that were found (imagehlp.dll can search for symbol files, rather than loading a specified symbol file).
If *OldFileSymbolPathArray or NewFileSymbolPath resolve to a complete file name, mspatchc.dll passes the path string along to imagehlp.dll, meaning that it is probably a path and not a file name.
Creating Deltas from Multiple Basis Files
Two functions allow the creation of deltas for multiple versions of the same basis file:
The OldFileCount parameter in these functions specifies the total number of basis files. The Delta created by these functions contains all of the deltas for the multiple basis files, and it can be applied to any of the basis files to produce the same target.
If a basis file is designated as NULL or INVALID_HANDLE_VALUE, only a single basis file can be used (OldFileCount = 1). See Compressing a Target Without a Basis File.
Ignore and Retain Ranges in Basis Files
It is possible to specify regions of the basis file to be ignored or retained during delta creation and signature calculation. Ignore range and retain range are defined as follows:
Ignore range: A region of the basis file that is not referenced during delta creation. The ignore range is also not included in the signature calculation on the basis file. Ignore ranges are useful in cases where files are modified at install time and therefore contain regions that are unique to each local copy.
Retain range: A region of the basis file that is copied to the delta. After decompression, the contents of the retain range are copied into the target at the appropriate location. Retain ranges are useful in cases where a defined region of the basis file must be retained in the target.
Two functions allow you to specify ignore and retain ranges during delta creation:
The OldFileInfoArray parameter is a pointer to a structure that defines portions of the basis file to ignore or retain. This structure can be one of the following types, defined in patchapi.h:
- PATCH_OLD_FILE_INFO_A. For ANSI paths.
- PATCH_OLD_FILE_INFO_W. For Unicode paths.
- PATCH_OLD_FILE_INFO_H. For files accessed by handles.
- PATCH_OLD_FILE_INFO, defined in patchapi.h:
typedef struct _PATCH_OLD_FILE_INFO {
ULONG SizeOfThisStruct;
union {
LPCSTR OldFileNameA;
LPCWSTR OldFileNameW;
HANDLE OldFileHandle;
};
ULONG IgnoreRangeCount;
PPATCH_IGNORE_RANGE IgnoreRangeArray;
ULONG RetainRangeCount;
PPATCH_RETAIN_RANGE RetainRangeArray;
} PATCH_OLD_FILE_INFO, *PPATCH_OLD_FILE_INFO;
Table 4. PATCH_OLD_FILE_INFO member descriptions
| Member | Description |
| SizeOfThisStruct | The size of this structure, in bytes, for validation |
| OldFileName
(or OldFileHandle) | The name (or handle) of the basis file |
| IgnoreRangeCount | The total number of ignore ranges in the basis file (see Ignore and Retain Ranges in Basis Files) |
| IgnoreRangeArray | Array of Ignore Ranges |
| RetainRangeCount | The total number of retain ranges in the basis file (see Ignore and Retain Ranges in Basis Files) |
| RetainRangeArray | Array of Retain Ranges |
The structures PATCH_IGNORE_RANGE and PATCH_RETAIN_RANGE are defined in patchapi.h:
typedef struct _PATCH_IGNORE_RANGE {
ULONG OffsetInOldFile;
ULONG LengthInBytes;
} PATCH_IGNORE_RANGE, *PPATCH_IGNORE_RANGE;
typedef struct _PATCH_RETAIN_RANGE {
ULONG OffsetInOldFile;
ULONG LengthInBytes;
ULONG OffsetInNewFile;
} PATCH_RETAIN_RANGE, *PPATCH_RETAIN_RANGE;
Each version of the basis file must have the same RetainRangeCount and the same retain range LengthInBytes and OffsetInNewFile values in the same order. Only the OffsetInOldFile values can differ between basis file versions for retain ranges.
Normalized File Signatures
In many cases, files that are otherwise the same contain subtle differences such as timestamps, binding, and rebase information. If a full hash identifies these files, the compressor would consider them to be entirely different, which would result in the creation of deltas between files that are essentially identical. To handle this problem, the Delta Compression API provides a function for calculating a normalized signature. A normalized signature is a hash that is calculated after timestamp, binding, and rebase values have been set to zero. The result is a hash that represents only the portions of the file that are meaningful for Delta Compression.
The normalization described here is only for the purpose of calculating normalized signatures. In all cases, the target file that results from a delta apply will be bit-by-bit identical to the original target file that was used to create the delta.
Normalization is file-type specific. The current version of the API performs normalization only for PE32 type files.
Note It is possible for two files to have the same normalized signature but not be equivalent for a delta apply. The fact that two files have the same normalized signature does not always mean that the delta apply will succeed with both, but these instances are rare.
The GetFilePatchSignature functions calculate a normalized signature for a given basis file. This is useful in situations where a delta is to be applied on several machines, which may already contain several versions of the basis file that differ only by timestamp, binding, and rebase information.
Flags
The API supports different flags to specify options. The flags can be grouped as follows:
- Delta Creation Flags
- Delta Apply Flags
- Symbol Option Flags
- Get Signature Flags
Multiple flags can be specified by using a bitwise OR. For example:
OptionFlags = FLAG1 | FLAG2 | FLAG3
Delta Creation Flags
The following table lists the flags that can be combined and supplied as the OptionFlags parameter in CreatePatchFile functions to specify options during delta creation. These options mainly include specific transform instructions (i.e., how to preprocess this file before passing into the LZX compressor), as well as some other options. Since the same preprocessing needs to be carried out on delta apply, these flags are encoded into the delta as well. The ExtractPatchHeader functions extract the flags as well as other header information from the delta.
Table 5. Delta Creation flag descriptions
| Flag | Description |
| PATCH_OPTION_FAIL_IF_BIGGER | Fail if delta is larger than simply compressing the target without comparison to the basis file. Setting this flag makes the Delta Create process slower because the compressor internally compresses the target both as a delta and as a standalone file just so it can make the comparison. See ERROR_PATCH_BIGGER_THAN_COMPRESSED, under Error Codes. |
| PATCH_OPTION_FAIL_IF_SAME_FILE | Don't create a delta if basis file and target are the same or differ only by normalization. |
| PATCH_OPTION_NO_BINDFIX | Portable executable bound imports. |
| PATCH_OPTION_NO_CHECKSUM | Portable executable checksum zero. |
| PATCH_OPTION_NO_LOCKFIX | Portable executable smashed locks. |
| PATCH_OPTION_NO_REBASE | Portable executable rebased image. |
| PATCH_OPTION_NO_RESTIMEFIX | Portable executable resource timestamps. |
| PATCH_OPTION_NO_TIMESTAMP | Don't store new file timestamp in patch. |
| PATCH_OPTION_RESERVED1 | Reserved. |
| PATCH_OPTION_SIGNATURE_MD5 | Use MD5 instead of CRC32. |
| PATCH_OPTION_USE_BEST | Auto-choose best of LZX_A or LZX_B (slower). Equivalent to PATCH_OPTION_USE_LZX_BEST. |
| PATCH_OPTION_USE_LZX_A | Normal (LZ) compression. |
| PATCH_OPTION_USE_LZX_B | Better on some x86 binaries. |
| PATCH_OPTION_USE_LZX_BEST | Auto-choose best of LZX_A or LZX_B (slower). Equivalent to PATCH_OPTION_USE_BEST in version 1.9. |
| PATCH_OPTION_USE_LZX_LARGE | Better support for files larger than 8 MB. |
| PATCH_OPTION_VALID_FLAGS | The logical OR of all valid delta creation flags. |
Delta Apply Flags
The following table lists the flags for delta apply. These can be combined and used as the ApplyOptionFlags parameter in ApplyPatchToFile and TestApplyPatchToFile functions.
Table 6. Delta Apply flag descriptions
| Flag | Description |
| APPLY_OPTION_FAIL_IF_EXACT | If the basis file and the target will be the same, return a failure and don't create the target. |
| APPLY_OPTION_FAIL_IF_CLOSE | If the basis file and the target differ by only rebase and bind information (that is, they have the same normalized signature), return a failure and don't create the target. |
| APPLY_OPTION_TEST_ONLY | Don't create the target. |
| APPLY_OPTION_VALID_FLAGS | The logical OR of all valid delta apply flags. |
Symbol Option Flags
The following flags are used with PATCH_OPTION_DATA SymbolOptionFlags (see Optional Data for Delta Create).
Table 7. Symbol Option flag descriptions
| Flag | Description |
| PATCH_SYMBOL_NO_FAILURES | Create the delta even if imagehlp.dll failures occur. |
| PATCH_SYMBOL_NO_IMAGEHLP | Don't use imagehlp.dll. |
| PATCH_SYMBOL_RESERVED1 | Reserved. |
| PATCH_SYMBOL_UNDECORATED_TOO | After matching decorated symbols, try to match remaining by undecorated names. |
Get Signature Flags
The flags in the following table can be combined and used as the OptionFlags parameter in the GetFilePatchSignature functions.
Table 8. Get signature flag descriptions
| Flag | Description |
| PATCH_OPTION_NO_BINDFIX | Portable executable bound imports. |
| PATCH_OPTION_NO_CHECKSUM | Portable executable checksum zero. |
| PATCH_OPTION_NO_LOCKFIX | Portable executable smashed locks. |
| PATCH_OPTION_NO_REBASE | Portable executable rebased image. |
| PATCH_OPTION_NO_RESTIMEFIX | Portable executable resource timestamps. |
| PATCH_OPTION_NO_TIMESTAMP | Don't store new file timestamp in patch. |
| PATCH_OPTION_SIGNATURE_MD5 | Use MD5 instead of CRC32. |
Error Codes
When a function returns FALSE, the caller can call GetLastError to get the corresponding error code. There are no HRESULT codes, and the failure code might be an underlying Win32 failure (such as ERROR_OUTOFMEMORY or ERROR_DISK_FULL) or a delta-specific error (listed in the following two tables).
Table 9. Delta Creation error codes
| Error Code | Description |
| ERROR_PATCH_ENCODE_FAILURE | Generic encoding failure. Could not create delta. |
| ERROR_PATCH_INVALID_OPTIONS | Invalid options were specified. |
| ERROR_PATCH_SAME_FILE | The basis file and target are the same. |
| ERROR_PATCH_RETAIN_RANGES_DIFFER | Retain ranges specified in multiple basis files are different (see Ignore and Retain Ranges in Basis Files). |
| ERROR_PATCH_BIGGER_THAN_COMPRESSED | The delta is larger than simply compressing the target without comparison to the basis file. This error is returned only if the PATCH_OPTION_FAIL_IF_BIGGER flag is set (see Delta Creation Flags). |
| ERROR_PATCH_IMAGEHLP_FAILURE | Could not obtain symbols. |
Table 10. Delta Apply error codes
| Error Code | Description |
| ERROR_PATCH_DECODE_FAILURE | The delta is corrupted. |
| ERROR_PATCH_CORRUPT | The delta is corrupted. |
| ERROR_PATCH_NEWER_FORMAT | The delta was created using a compression algorithm that is not compatible with the basis file. |
| ERROR_PATCH_WRONG_FILE | The delta and the basis file are not from the same file. |
| ERROR_PATCH_NOT_NECESSARY | The basis file and target are the same, or they differ only by normalization. This error is returned only if the PATCH_OPTION_FAIL_IF_SAME_FILE flag is set (see Delta Creation Flags). |
| ERROR_PATCH_NOT_AVAILABLE | Delta consists of only an extracted header and an ApplyPatchToFile function is called instead of a Test ApplyPatchToFile function. |
Function Reference
This section provides an alphabetical listing of all API functions, with descriptions of each one.
ApplyPatchToFile
The ApplyPatchToFile function applies a given delta to a given basis file and writes the resultant target to disk.
BOOL PATCHAPI ApplyPatchToFile(
LPCTSTR PatchFileName,
LPCTSTR OldFileName,
LPCTSTR NewFileName,
ULONG ApplyOptionFlags,
);
Table 11. Function parameter descriptions
| Parameter | Description |
| PatchFileName | The name of the delta that is applied to the basis file. |
| OldFileName | The name of the basis file to which the delta is applied. |
| NewFileName | The name of the target file that is created. |
| ApplyOptionFlags | APPLY_OPTION_nnn flags (see Delta Apply Flags). |
Return Values
Returns TRUE on success or FALSE otherwise. See also Error Codes.
Table 12. Requirements
See Also
ApplyPatchToFileByHandles
The ApplyPatchToFileByHandles function applies a given delta to a given basis file and writes the resultant target to disk. File locations are specified by handles.
BOOL PATCHAPI ApplyPatchToFileByHandles(
HANDLE PatchFileHandle,
HANDLE OldFileHandle,
HANDLE NewFileHandle,
ULONG ApplyOptionFlags
)
Table 13. Function parameter descriptions
| Parameter | Description |
| PatchFileHandle | Handle to the delta that is applied to the basis file. Requires GENERIC_READ access. |
| OldFileHandle | Handle to the basis file to which the delta is applied. Requires GENERIC_READ access. |
| NewFileHandle | Handle to the target file that is created. Requires GENERIC_READ | GENERIC_WRITE. |
| ApplyOptionFlags | APPLY_OPTION_nnn flags (see Delta Apply Flags). |
Return Values
Returns TRUE on success or FALSE otherwise. See also Error Codes.
Table 14. Requirements
| Delta Compression API | 1.9 |
| Header | Declared in patchapi.h |
| DLL | Requires mspatcha.dll |
| Unicode | Not applicable |
See Also
ApplyPatchToFileByHandlesEx
The ApplyPatchToFileByHandlesEx function applies a given delta to a given basis file and writes the resultant target to disk. File locations are specified by handles. This function provides progress reporting during the apply process.
BOOL PATCHAPI ApplyPatchToFileByHandlesEx(
HANDLE PatchFileHandle,
HANDLE OldFileHandle,
HANDLE NewFileHandle,
ULONG ApplyOptionFlags,
PPATCH_PROGRESS_CALLBACK ProgressCallback,
PVOID CallbackContext
)
Table 15. Function parameter descriptions
| Parameter | Description |
| PatchFileHandle | Handle to the delta that is applied to the basis file. Requires GENERIC_READ access. |
| OldFileHandle | Handle to the basis file to which the delta is applied. Requires GENERIC_READ access. |
| NewFileHandle | Handle to the target file that is created. Requires GENERIC_READ | GENERIC_WRITE. |
| ApplyOptionFlags | APPLY_OPTION_nnn flags (see Delta Apply Flags). |
| ProgressCallback | Pointer to application-defined callback function (see Progress Callback). |
| CallbackContext | Pointer to application-defined context (see Progress Callback). |
Return Values
Returns TRUE on success or FALSE otherwise. See also Error Codes.
Table 16. Requirements
| Delta Compression API | 1.9 |
| Header | Declared in patchapi.h |
| DLL | Requires mspatcha.dll |
| Unicode | Not applicable |
See Also
ApplyPatchToFileEx
The ApplyPatchToFileEx function applies a given delta to a given basis file and writes the resultant target to disk. This function provides progress reporting during the apply process.
BOOL PATCHAPI ApplyPatchToFileEx(
LPCTSTR PatchFileName,
LPCTSTR OldFileName,
LPCTSTR NewFileName,
ULONG ApplyOptionFlags,
PPATCH_PROGRESS_CALLBACK ProgressCallback,
PVOID CallbackContext
)
Table 17. Function parameter descriptions
| Parameter | Description |
| PatchFileName | The name of the delta that is applied to the basis file. |
| OldFileName | The name of the basis file to which the delta is applied. |
| NewFileName | The name of the target file that is created. |
| ApplyOptionFlags | APPLY_OPTIONS_xxx flags (see Delta Apply Flags). |
| ProgressCallback | Pointer to application-defined callback function (see Progress Callback). |
| CallbackContext | Pointer to application-defined context (see Progress Callback). |
Return Values
Returns TRUE on success or FALSE otherwise. See also Error Codes.
Table 18. Requirements
| Delta Compression API | 1.9 |
| Header | Declared in patchapi.h |
| DLL | Requires mspatcha.dll |
| Unicode | Not applicable |
See Also
CreatePatchFile
The CreatePatchFile function creates a delta from a given basis file and a given target and writes the resultant delta to disk.
BOOL PATCHAPI CreatePatchFile(
LPCTSTR OldFileName,
LPCTSTR NewFileName,
LPCTSTR PatchFileName,
ULONG OptionFlags,
PPATCH_OPTION_DATA OptionData
);
Table 19. Function parameter descriptions
| Parameter | Description |
| OldFileName | The name of the basis file to which the target file is compared. |
| NewFileName | The name of the target file that is compared to the basis file. |
| PatchFileName | The name of the delta that is created. |
| OptionFlags | PATCH_OPTION_nnn flags. See Delta Creation Flags. |
| OptionData | Pointer to a structure containing delta creation options. See Optional Data for Delta Create. |
Return Values
Returns TRUE on success or FALSE otherwise. See also Error Codes.
Table 20. Requirements
See Also
CreatePatchFileByHandles
The CreatePatchFileByHandles function creates a delta from a given basis file and a given target and writes the resultant delta to disk. File locations are specified by handles.
BOOL PATCHAPI CreatePatchFileByHandles(
HANDLE OldFileHandle,
HANDLE NewFileHandle,
HANDLE PatchFileHandle,
ULONG OptionFlags,
PPATCH_OPTION_DATA OptionData
)
Table 21. Function parameter descriptions
| Parameter | Description |
| OldFileHandle | Handle to the basis file to which the target file is compared. |
| NewFileHandle | Handle to the target file that is compared to the basis file. |
| PatchFileHandle | Handle to the delta that is created. |
| OptionFlags | PATCH_OPTION_nnn flags (see Delta Creation Flags). |
| OptionData | Pointer to a structure containing delta creation options (see Optional Data for Delta Create). |
Return Values
Returns TRUE on success or FALSE otherwise. See also Error Codes.
Table 22. Requirements
| Delta Compression API | 1.9 |
| Header | Declared in patchapi.h |
| DLL | Requires mspatchc.dll |
| Unicode | Not applicable |
See Also
CreatePatchFileByHandlesEx
The CreatePatchFileByHandlesEx function creates a delta from a given basis file and a given target and writes the resultant delta to disk. File locations are specified by handles. This function provides progress reporting during the create process.
BOOL PATCHAPI CreatePatchFileByHandlesEx(
ULONG OldFileCount,
PPATCH_OLD_FILE_INFO_H OldFileInfoArray,
HANDLE NewFileHandle,
HANDLE PatchFileHandle,
ULONG OptionFlags,
PPATCH_OPTION_DATA OptionData,
PPATCH_PROGRESS_CALLBACK ProgressCallback,
PVOID CallbackContext
)
Table 23. Function parameter descriptions
Return Values
Returns TRUE on success or FALSE otherwise. See also Error Codes.
Table 24. Requirements
| Delta Compression API | 1.9 |
| Header | Declared in patchapi.h |
| DLL | Requires mspatchc.dll |
| Unicode | Not applicable |
See Also
CreatePatchFileEx
The CreatePatchFileEx function creates a delta from a given basis file and a given target and writes the resultant delta to disk. This function provides progress reporting during the create process.
BOOL PATCHAPI CreatePatchFileEx(
ULONG OldFileCount,
PPATCH_OLD_FILE_INFO_A OldFileInfoArray,
LPCTSTR NewFileName,
LPCTSTR PatchFileName,
ULONG OptionFlags,
PPATCH_OPTION_DATA OptionData,
PPATCH_PROGRESS_CALLBACK ProgressCallback,
PVOID CallbackContext
)
Table 25. Function parameter descriptions
Return Values
Returns TRUE on success or FALSE otherwise. See also Error Codes.
Table 26. Requirements
See Also
ExtractPatchHeaderToFile
The ExtractPatchHeaderToFile function extracts the header information from a given delta and writes the resultant header file to disk.
BOOL PATCHAPI ExtractPatchHeaderToFile(
LPCTSTR PatchFileName,
LPCTSTR PatchHeaderFileName
)
Table 27. Function parameter descriptions
| Parameter | Description |
| PatchFileName | The name of the delta containing the header. |
| PatchHeaderFileName | The name of the header file that is created. |
Return Values
Returns TRUE on success or FALSE otherwise. See also Error Codes.
Table 28. Requirements
| Delta Compression API | 1.9 |
| Header | Declared in patchapi.h |
| DLL | Requires mspatchc.dll |
| Unicode | Implemented as ExtractPatchHeaderToFileW (Unicode) and ExtractPatchHeaderToFileA (ANSI) |
See Also
ExtractPatchHeaderToFileByHandles
The ExtractPatchHeaderToFileByHandles function extracts the header information from a given delta and writes the resultant header to disk. File locations are specified by handles.
BOOL PATCHAPI ExtractPatchHeaderToFileByHandles(
HANDLE PatchFileHandle,
HANDLE PatchHeaderFileHandle
)
Table 29. Function parameter descriptions
| Parameter | Description |
| PatchFileName | Handle to the delta containing the header. |
| PatchHeaderFileName | Handle to the header file that is created. |
Return Values
Returns TRUE on success or FALSE otherwise. See also Error Codes.
Table 30. Requirements
| Delta Compression API | 1.9 |
| Header | Declared in patchapi.h |
| DLL | Requires mspatchc.dll |
| Unicode | Not applicable |
See Also
GetFilePatchSignature
The GetFilePatchSignature function calculates a normalized signature for a given file and writes it to a specified buffer.
BOOL PATCHAPI GetFilePatchSignature(
LPCTSTR FileName,
ULONG OptionFlags,
PVOID OptionData,
ULONG IgnoreRangeCount,
PPATCH_IGNORE_RANGE IgnoreRangeArray,
ULONG RetainRangeCount,
PPATCH_RETAIN_RANGE RetainRangeArray,
ULONG SignatureBufferSize,
PVOID SignatureBuffer
)
Table 31. Function parameter descriptions
Return Values
Returns TRUE on success or FALSE otherwise. See also Error Codes.
Table 32. Requirements
| Delta Compression API | 1.9 |
| Header | Declared in patchapi.h |
| DLL | Requires mspatcha.dll or mspatchc.dll |
| Unicode | Implemented as GetFilePatchSignatureW (Unicode) and GetFilePatchSignatureA (ANSI). |
See Also
GetFilePatchSignatureByHandle
The GetFilePatchSignatureByHandle function calculates a normalized signature for a given file and writes it to a specified buffer. The file location is specified by a handle.
BOOL PATCHAPI GetFilePatchSignatureByHandle(
HANDLE FileHandle,
ULONG OptionFlags,
PVOID OptionData,
ULONG IgnoreRangeCount,
PPATCH_IGNORE_RANGE IgnoreRangeArray,
ULONG RetainRangeCount,
PPATCH_RETAIN_RANGE RetainRangeArray,
ULONG SignatureBufferSize,
PVOID SignatureBuffer
)
Table 33. Function parameter descriptions
Return Values
Returns TRUE on success or FALSE otherwise. See also Error Codes.
Table 34. Requirements
| Delta Compression API | 1.9 |
| Header | Declared in patchapi.h |
| DLL | Requires mspatcha.dll or mspatchc.dll |
| Unicode | Not applicable |
See Also
TestApplyPatchToFile
The TestApplyPatchToFile function verifies that a given delta or delta header matches a given basis file. This function does not actually apply the delta.
BOOL PATCHAPI TestApplyPatchToFile(
LPCTSTR PatchFileName,
LPCTSTR OldFileName,
ULONG ApplyOptionFlags
)
Table 35. Function parameter descriptions
| Parameter | Description |
| PatchFileName | The name of the delta that is checked against the basis file. |
| OldFileName | The name of the basis file that is checked against the delta. |
| ApplyOptionFlags | APPLY_OPTION_nnn flags (see Delta Apply Flags). |
Return Values
Returns TRUE if the delta matches the basis file or FALSE otherwise. See also Error Codes.
Table 36. Requirements
| Delta Compression API | 1.9 |
| Header | Declared in patchapi.h |
| DLL | Requires mspatcha.dll |
| Unicode | Implemented as TestApplyPatchToFileW (Unicode) and TestApplyPatchToFileA (ANSI) |
See Also
TestApplyPatchToFileByHandles
The TestApplyPatchToFileByHandles function verifies that a given delta or delta header matches a given basis file. File locations are specified by handles. This function does not actually apply the delta.
BOOL PATCHAPI TestApplyPatchToFileByHandles(
HANDLE PatchFileHandle,
HANDLE OldFileHandle,
ULONG ApplyOptionFlags
)
Table 37. Function parameter descriptions
| Parameter | Description |
| PatchFileHandle | Handle to the delta. Requires GENERIC_READ access. |
| OldFileHandle | Handle to the basis file to be checked against the delta. Requires GENERIC_READ access. |
| ApplyOptionFlags | APPLY_OPTION_nnn flags (see Delta Apply Flags). |
Return Values
Returns TRUE if the delta matches the basis file or FALSE otherwise. See also Error Codes.
Table 38. Requirements
| Delta Compression API | 1.9 |
| Header | Declared in patchapi.h |
| DLL | Requires mspatcha.dll |
| Unicode | Not applicable |
See Also
Practical Usage
Delta compression technology has been successfully used to deploy software updates for Microsoft Windows XP, Microsoft Windows Server 2003, and Microsoft Windows 2000 operating systems. This technology is part of the Package Installer for Windows, and it reduces the download size of software update packages by downloading the differences between old files and new files during the software update process. When the old file does not exist, the installer downloads the entire updated file in its compressed form.
Downloads from Windows Update version 5.0 or later support the use of the Background Intelligent Transfer Service (BITS), which asynchronously transfers update files while preserving the responsiveness of other network applications and which automatically resumes file transfers after restarts or network disconnects. These update installations use Microsoft Software Update Services (SUS) version 5.0 (or later), which enables updates to be downloaded from any server that supports HTTP 1.1, thereby reducing server traffic.
For more information on the Package Installer for Windows, see The Package Installer (Formerly Called Update.exe) for Microsoft Windows Operating Systems and Windows Components.
White Papers on Delta Compression
Binary Delta Compression
Using Binary Delta Compression (BDC) Technology and Background Intelligent Transfer Service (BITS) for Software Updates to Windows XP and Windows Server 2003
Glossary
Basis File
During delta creation, the file to which the target is compared. During delta application, the file to which the delta is applied. Also called reference, source, or old file.
Delta
A file that represents the difference between two files. Also called a patch.
Flags
Integers defined in patchapi.h that allow specific options to be set during calls. See Flags for details.
LZ (Lempel-Ziv) Compression
A substitutional compression scheme proposed by Jakob Ziv and Abraham Lempel. It is built upon the variable-length Huffman encoding algorithm, but it exploits pattern matching, displacement, and length as well as frequency bias. In LZ compression, a sliding window is passed over the data stream and all patterns in the window at a given time are encoded.
MD5 Signature
File signature produced by using the MD5 algorithm. The MD5 algorithm creates a 128-bit signature for an input of arbitrary length. It is used as a way to check data integrity.
"MD5" refers to the RSA Data Security, Inc. MD5 Message-Digest Algorithm, as described in RFC 1321.
Normalized Signature
A hash that is calculated after timestamp, binding, and rebase values have been set to zero.
PE32
32-bit portable executable file.
Target
During delta creation, the file that is compared to the basis file. During delta application, the file that is output by applying a delta to a basis file. Also called new file.
Transforms
Preprocessing instructions that allow the Delta Compression Engine to annul cascading changes in a file that result from changing a small part of it. Especially useful when creating deltas between files with embedded pointers.