Delta Compression Application Programming Interfaces
Microsoft Corporation
July 2013
Delta Compression is a differential compression technology developed by Microsoft. While it has mainly been used for Windows Updates, Delta Compression offers other uses as well. The following topics discuss Delta Compression Application Programming Interfaces (APIs) currently available in the Windows Platform.
Notes on Terminology
The terms source, target, and delta are used throughout this documentation. Previous documents used different terms:
- old file or basis is now source—the file against which the new file (the target) is compared.
- new file is now target—the new file
- patch is now delta—the file containing compressed difference between the source and target.
Although some descriptions and parameters reflect the earlier usage, the text in this document uses the new terminology for consistency with ongoing development.
The term "Apply" is used to describe the decompression process, but please note that "Apply" never means to modify an existing file. This process always produces a completely new target file.
| Interface | Description |
|---|---|
| PatchAPI | C-Language based API that allows you to create and apply deltas. Lower computational overhead than MSDelta but typically creates larger deltas.
Applies to: |
| MSDelta | C-Language based API that allows you to create and apply deltas. MSDelta offers optimization for a much larger range of file types than PatchAPI.
Applies to: |
Developer Audience
This documentation is intended for software developers who want to programmatically create deltas (similare to patches or compressed diffs) between files. General information about the various APIs is included in this documentation. It provides information about delta compression and the Delta Compression APIs. This documentation provides descriptions of the functions as well as supplemental information for developers who want to optimize the size of their deltas for certain file types.
See Also
- Introduction to Microsoft Delta Compression
General information about Microsoft Delta Compression technology. - Delta Compression Glossary
Defines the various terms used in this documentation. - KB927374
The Microsoft Compression Client Pack 1.0 for Windows XP and Windows Server 2003
Legal Information
Microsoft Compression Technologies
Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.
Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.
Microsoft, Microsoft Press, MS-DOS, MSDN, ActiveX, BackOffice, DirectX, JScript, Visual Basic, Visual C++, Windows, Win32, Win32s, Windows NT, Windows Vista, and Windows Server are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
The names of actual companies and products mentioned herein may be the trademarks of their respective owners.
© 2009 Microsoft Corporation. All rights reserved.
Introduction to Delta Compression
Delta Compression was originally designed as a faster, more efficient way to deliver updates and patches. While it remains an ideal method for distributing necessary updates, it also offers a wide range of other applications. Delta Compression takes advantage of the similarities between files and can create significantly smaller compressed files than those produced by other compression methods.
Topics in this section
- Overview of Delta Compression Technology
- Transforms
- Delta Compression Effectiveness
Overview of Delta Compression Technology
In conventional compression, the compressor takes a file and produces a more compact representation of that file. The decompressor performs the reverse function, taking the compact form and creating an exact copy of the original file.
Figure 1 illustrates this process. The compressor takes some data F' and produces a compact representation C(F'). Later, the decompressor takes C(F') and creates an exact copy of data F'.
.gif "Bb417345.bdcapi_01(en-us,MSDN.10).gif")
Figure 1. Conventional data compression
Delta Compression uses a compressor that accepts two inputs. One of these is the target file to be compressed. The other is a reference source file. The delta creator locates and copies the differences between the target and source file, compressing only those differences as a delta.
The decompressor, or applier, takes the delta and source files as input to create an exact copy of the target.
Figure 2 illustrates the Delta compression and decompression processes. The delta creator takes target compressible data F' along with source F. The delta creator produces a compressed representation ΔF-F'. Later, the delta applier accepts the delta ΔF-F' along with the same source F, and reconstructs the target data F'.
.gif "Bb417345.bdcapi_02(en-us,MSDN.10).gif")
Figure 2. Delta compression
Transforms
A Transform is preprocessing performed by PatchAPI or MSDelta which modifies the source to make it more similar to the target at the byte level, prior to delta creation (increasing the likelihood of producing a smaller delta). Transforms are specific to the file type of the source. Transforms are used by both the delta Create and Apply functions as described below.
Delta Create using Transforms performs four steps:
- Determines the file type of the source.
- Preprocesses the source and creates source preprocessing information specific to the determined file type, the target, and optional parameters. (Transform Procedure)
- Creates the compression stream for the target.
- Packages the source preprocessing information and compression stream in a single buffer, resulting in the delta output. (Create Procedure)
Delta Apply using Transforms performs two major steps:
- Preprocesses the source according to its file type and the source preprocessing information embedded in the delta to produce the preprocessed source buffer. (Transform Procedure)
- Applies the byte-level differences to the preprocessed source buffer according to the compression stream embedded in the delta, resulting in the target output.
(Apply Procedure).
The source preprocessing information output from step 2 of the Create preprocessing is identical to the source preprocessing information output from step 1 of the Apply preprocessing.
Transforms are especially effective when creating deltas between structured file types. PatchAPI contains Transforms for i386 executables files while MSDelta contains Transforms for i386, ia64 and amd64 executable files.
Delta Compression Effectiveness
The delta will be small when files F and F' are similar. One common scenario is when the source is an older version of the target. The differences between these two versions might be minor which means the delta will be small since it is a compressed version of those differences.
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 source is still compressed. In some cases, where the source and target have nothing in common, the delta is equivalent to a compressed form of the target. Some data is inherently not compressible, and the "compressed" version of such data may actually be larger than the original data. This is true of any lossless compression technique.
PatchAPI also offers special handling (Transforms) for some file types, most notably PE (Portable Executable) files. (For more information about PE files, please refer to the MSDN Magazine article entitled An In-Depth Look into the Win32 Portable Executable File Format) When the source and target files are similar PE files, the size of the delta can typically be made 50-70% smaller than without this special treatment.
To get the maximum benefit from this feature in PatchAPI, symbol files from the LINK process can be supplied during delta creation. This will help the Create process recognize the nature of the changes between the files. Richer symbol information, such as private symbols, will help make smaller deltas. Figure 3 illustrates this process.
.gif "Bb417345.bdcapi_03(en-us,MSDN.10).gif")
Figure 3. Delta compression using symbol files in PatchAPI
PatchAPI
Microsoft Corporation
October 2009
Purpose
PatchAPI is a differential compression library that can create much smaller compressed files than those produced by other methods. It has been used to deploy software updates for Microsoft Windows and in Windows Installer Patch (MSP) Files.
Applies to:
Microsoft® Windows XP®
Windows 2000®
Windows Server 2003®
Windows Vista®
Windows Server 2008®
Windows 7®
Windows Server 2008 R2®
Getting the PatchAPI Components
The PatchAPI includes the following files:
- mspatcha.dll: Dynamic link library for applying deltas. This library is shipped with Windows XP, Windows 2000, Windows Server 2003, Windows Vista, Windows Server 2008, Windows 7, and Windows 2008 R2. It can be found in the System32 directory.
- mspatchc.dll: Dynamic-link library for creating deltas. This library is part of the current version of the Windows Platform SDK.
- patchapi.h: Header file that defines the API functions, structures, and constants. This header is part of the current version of the Windows Platform SDK.
Run-Time Requirements
PatchAPI runs on Windows XP, Windows 2000, Windows Server 2003, and Windows Vista. To create deltas, imagehlp.dll must also be installed on your computer.
- PatchAPI Reference
Descriptions of the various PatchAPI functions, flags, and error codes. - Compressing a Target Without a Source File
Describes how the API functions can be used to create a delta without referencing a source file. - Progress Callback
Describes the reporting structures used during Create and Apply. - Creating Deltas from Multiple Source Files
Describes the API for creating a single delta that applies to several different source files. - Ignore and Retain Ranges in Source Files
Describes how to identify regions of the source file for special treatment during delta creation and signature calculation. - Normalized File Signatures
Describes how the GetFilePatchSignature functions can be used to select a delta when there are several source files. - Flags
Describes the flags that can be used to specify options for different operations. - Error Codes
Lists some of the special error codes that may be returned when an API call fails.
Compressing a Target Without a Source File
If a CreatePatch function is called and the source file is specified as NULL or INVALID_HANDLE_VALUE, the output will be a compressed representation of the target file. However, for functions that support multiple source files, NULL or INVALID_HANDLE_VALUE can be supplied only when a single source file is used (OldFileCount = 1).
See Also
- CreatePatch Functions
- Creating Deltas from Multiple Source Files
Progress Callback
The following functions provide progress reporting through a caller-specified progress callback function:
- CreatePatchFileEx
- CreatePatchFileByHandlesEx
- ApplyPatchToFileEx
- ApplyPatchToFileByHandlesEx
- ApplyPatchToFileByBuffers
A callback provided to 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
);
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 should return a BOOL value. A TRUE return value allows processing to continue. A FALSE return value will cause the API to fail.
Optional Data for Patch Create
The following functions accept parameters for optional data of type PATCH_OPTION_DATA, which is described below.
- CreatePatchFile
- CreatePatchFileByHandles
- CreatePatchFileEx
- CreatePatchFileByHandlesEx
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;
PPATCH_INTERLEAVE_MAP* InterleaveMapArray;
ULONG MaxLzxWindowSize;
} PATCH_OPTION_DATA, *PPATCH_OPTION_DATA;
PATCH_OPTION_DATA member descriptions
| Member | Description |
|---|---|
| SizeOfThisStruct | The size of this structure, in bytes, for validation. |
| SymbolOptionFlags | The Symbol Option Flags to use with this structure. |
| NewFileSymbolPath | The path to the directory containing symbol files (.pdb) for the target.
Note: Always ANSI, never Unicode. |
| OldFileSymbolPathArray | A pointer to an array containing the paths to directories containing symbol files (.pdb) for the source file. |
| ExtendedOptionFlags | Reserved. |
| SymLoadCallback | A pointer to application-defined symbol callback function. |
| SymLoadContext | A pointer to application-defined symbol context. |
| InterleaveMapArray | Reserved. |
| MaxLzxWindowSize | Reserved. |
PATCH_OPTION_DATA contains LPCSTR paths. No LPCWSTR (Unicode) path argument is available even when used with one of the Unicode APIs such as CreatePatchFileW. The 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. This member 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).
Creating Deltas from Multiple Source Files
Two functions create deltas that apply to multiple source files:
- CreatePatchFileEx
- CreatePatchFileByHandlesEx
The OldFileCount parameter in these functions specifies the total number of source files. The delta created by these functions can be applied to any of the source files to produce the same target.
If multiple source files are used (OldFileCount > 1), then none of them can be designated as NULL or INVALID_HANDLE_VALUE.
See also Compressing a Target Without a Source File.
Ignore and Retain Ranges in Source Files
It is possible to specify regions of the source 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 source file that is not referenced during delta creation. The ignore range is also not included in the signature calculation on the source 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 source file that is copied to the delta. This region is taken directly from the source with no comparison to the target. 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 source file must be retained in the target.
Two functions let the caller specify ignore and retain ranges during delta creation:
- CreatePatchFileEx
- CreatePatchFileByHandlesEx
The OldFileInfoArray parameter is a pointer to a structure that defines portions of the source 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 is 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;
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 source file. |
| IgnoreRangeCount | The total number of Ignore Ranges in the Source Files. |
| IgnoreRangeArray | Array of Ignore Ranges |
| RetainRangeCount | The total number of Retain Ranges in the Source 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;
When creating a delta from multiple source files, each version of the source file must have the same RetainRangeCount and the same retain range LengthInBytes and OffsetInNewFile values in the same order. Only the OffsetInOldFile values can be different between source file versions for retain ranges.
Normalized File Signatures
In many cases, PE files that are otherwise the same contain differences that can be ignored for the purposes of applying deltas. The PatchAPI provides a function for calculating a normalized signature. A normalized signature is a hash that is calculated after ignoring such differences. The result is a hash that represents only the portions of the file that are meaningful for applying deltas.
Note: It is possible for two files to have the same normalized signature but not be equivalent for applying deltas. The fact that two files have the same normalized signature does not always mean that the delta apply will succeed with both, but such instances are rare.
This API performs normalization only for i386 executable files.
The GetFilePatchSignature functions calculate a normalized signature for a given source file. This is useful in situations where a single delta is to be applied on several machines which may already contain slightly different variations of the source file that differ only by timestamp, binding, and rebase information. Those source files would all have the same normalized signature.
See Also
- GetFilePatchSignature
- NormalizeFileForPatchSignature
Flags
The API supports different flags to specify options. They can be grouped as follows:
- Patch Creation Flags
- Patch Apply Flags
- Symbol Option Flags
- Get Signature Flags
Multiple flags can be specified by using a bitwise OR. For example:
OptionFlags = FLAG1 | FLAG2 | FLAG3
CreatePatch 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 (how to preprocess this data before compressing), 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 ExtractPatchHeaderToFile functions extract the flags as well as other header information from the delta.
| Flag | Description |
|---|---|
| PATCH_OPTION_FAIL_IF_BIGGER | Fail if delta is larger than simply compressing the target without comparison to the source file. Setting this flag makes the Create process slower because the compressor compresses the target both as a delta and as a standalone file to make the comparison. See ERROR_PATCH_BIGGER_THAN_COMPRESSED, under Error Codes. |
| PATCH_OPTION_FAIL_IF_SAME_FILE | Don't create a delta if source file and target are the same or differ only by normalization. |
| PATCH_OPTION_NO_BINDFIX | Don't pre-process PE bound imports. |
| PATCH_OPTION_NO_CHECKSUM | Set PE checksum to zero. |
| PATCH_OPTION_NO_LOCKFIX | Don't repair disabled lock prefixes in source PE file. |
| PATCH_OPTION_NO_REBASE | Don't pre-process PE rebase information. |
| PATCH_OPTION_NO_RESTIMEFIX | Don't pre-process PE resource timestamps. |
| PATCH_OPTION_NO_TIMESTAMP | Don't store a timestamp in delta. |
| PATCH_OPTION_RESERVED1 | Reserved. |
| PATCH_OPTION_SIGNATURE_MD5 | Reserved. |
| 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 | Use standard LZX compression. |
| PATCH_OPTION_USE_LZX_B | Use alternate LZX compression.
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. |
| 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. |
ApplyPatch 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.
| Flag | Description |
|---|---|
| APPLY_OPTION_FAIL_IF_EXACT | If the source file and the target are the same, return a failure and don't create the target. |
| APPLY_OPTION_FAIL_IF_CLOSE | If the source 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 patch apply flags. |
Symbol Option Flags
The following flags are used with PATCH_OPTION_DATA SymbolOptionFlags.
| 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.
| Flag | Description |
|---|---|
| PATCH_OPTION_NO_BINDFIX | Don't pre-process PE bound imports. |
| PATCH_OPTION_NO_CHECKSUM | Set PE checksum to zero. |
| PATCH_OPTION_NO_LOCKFIX | Don't repair disabled lock prefixes in source PE file. |
| PATCH_OPTION_NO_REBASE | Don't pre-process PE rebase information. |
| PATCH_OPTION_SIGNATURE_MD5 | Use MD5 instead of CRC32. |
Error Codes
When a function returns FALSE, you 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 PatchAPI error (listed in the following two tables).
CreatePatch 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 source file and target are the same. |
| ERROR_PATCH_RETAIN_RANGES_DIFFER | Retain ranges specified in multiple source files are different (see Ignore and Retain Ranges in Source Files). |
| ERROR_PATCH_BIGGER_THAN_COMPRESSED | The delta is larger than simply compressing the target without comparison to the source 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. |
ApplyPatch error codes
| Error Code | Description |
|---|---|
| ERROR_PATCH_DECODE_FAILURE | The delta is corrupt. |
| ERROR_PATCH_CORRUPT | The delta is corrupt. |
| ERROR_PATCH_NEWER_FORMAT | The delta was created using a compression algorithm that is not compatible with the source file. |
| ERROR_PATCH_WRONG_FILE | The delta is not applicable to the source file. |
| ERROR_PATCH_NOT_NECESSARY | The source 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 CreatePatch Flags). |
| ERROR_PATCH_NOT_AVAILABLE | Delta consists of only an extracted header and an ApplyPatchToFile function is called instead of a TestApplyPatchToFile function. |
PatchAPI Reference
Microsoft Corporation
October 2009
Function topics include a description of the function, the syntax of the function, parameters associated with the function, and a requirements block that describes what platform, header files, and libraries are required.
Flags and error codes are listed and described in their own topics.
The tables below list the PatchAPI functions grouped by category.
Note: Most of the following functions have three variants associated with a suffix attached to the function name. *A functions support ANSI file paths. *W functions support Unicode file paths. *ByHandles functions support files accessed by handles. The *ByBuffers function supports files accessed as memory mapped buffers.
Note: The header file patchapi.h uses the -A suffix to identify functions that take ANSI arguments and the –W suffix to identify functions that take UNICODE arguments. To simplify usage the un-suffixed function name is conditionally redefined as the appropriate suffixed function name depending on whether UNICODE is defined or not at compile time. For example, if UNICODE is defined, CreatePatchFile is defined as CreatePatchFileW.
CreatePatch Functions
| Functions | Description |
|---|---|
CreatePatchFileA CreatePatchFileW CreatePatchFileByHandles |
Create deltas without progress reporting. |
CreatePatchFileExA CreatePatchFileExW CreatePatchFileByHandlesEx |
Create deltas with progress reporting (see Progress Callbacks).
Supports Creating Deltas from Multiple Source Files. Supports Ignore and Retain Ranges in Source Files. |
ApplyPatch Functions
| Functions | Description |
|---|---|
ApplyPatchToFileA ApplyPatchToFileW ApplyPatchToFileByHandles ApplyPatchToFileByBuffers |
Apply deltas without progress reporting. |
ApplyPatchToFileExA ApplyPatchToFileExW ApplyPatchToFileByHandlesEx |
Apply deltas with progress reporting (see Progress Callbacks). |
TestApplyPatchToFileA TestApplyPatchToFileW TestApplyPatchToFileByHandles TestApplyPatchToFileByBuffers |
Verify that a delta or delta header matches a source file that it is being applied to.
These functions do not actually apply deltas. |
Extract Patch Headers
| Functions | Description |
|---|---|
ExtractPatchHeaderToFileA ExtractPatchHeaderToFileW ExtractPatchHeaderToFileByHandles |
Extract information from deltas. |
Get Signatures
| Functions | Description |
|---|---|
GetFilePatchSignatureA GetFilePatchSignatureW GetFilePatchSignatureByHandle GetFilePatchSignatureByBuffer |
Calculate normalized signatures for identifying possible source files (see Normalized File Signatures). |
NormalizeFileForPatchSignature |
Perform the same normalization as the GetFilePatchSignature functions on a given buffer, without calculating a signature. |
See Also
- Compressing a Target Without a Source File
Describes how the API functions can be used to create a delta without referencing a source file. - Progress Callback
Describes the reporting structures used during Create and Apply. - Creating Deltas from Multiple Source Files
Describes the API for creating a single delta that applies to several different source files. - Ignore and Retain Ranges in Source Files
Describes how to identify regions of the source file for special treatment during delta creation and signature calculation. - Normalized File Signatures
Describes how the GetFilePatchSignature functions can be used to select a delta when there are several source files. - Flags
Describes the flags that can be used to specify options for different operations.
Error Codes
Lists some of the special error codes that may be returned when an API call fails.
CreatePatchFileA/W
The CreatePatchFileA and CreatePatchFileW functions create a delta from the specified source and target files and write the delta to the designated file name.
BOOL PATCHAPI CreatePatchFileA(
LPCTSTR OldFileName,
LPCTSTR NewFileName,
LPCTSTR PatchFileName,
ULONG OptionFlags,
PPATCH_OPTION_DATA OptionData
);
BOOL PATCHAPI CreatePatchFileW(
LPCWSTR OldFileName,
LPCWSTR NewFileName,
LPCWSTR PatchFileName,
ULONG OptionFlags,
PPATCH_OPTION_DATA OptionData
);
Parameters
OldFileName
The name of the source file.
NewFileName
The name of the target file.
PatchFileName
The name of the output delta file.
OptionFlags
Creation Flags.
Return Values
Returns TRUE on success or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in patchapi.h |
| DLL | Requires mspatchc.dll |
| Unicode | Implemented as CreatePatchFileW (Unicode) and CreatePatchFileA (ANSI) |
See Also
- CreatePatchFileByHandles
- CreatePatchFileByHandlesEx
- CreatePatchFileEx
CreatePatchFileByHandles
The CreatePatchFileByHandles function creates a delta between the specified source file and the specified target file. Both the source and the target file are provided as file handles. The output delta is also written to a provided file handle.
BOOL PATCHAPI CreatePatchFileByHandles(
HANDLE OldFileHandle,
HANDLE NewFileHandle,
HANDLE PatchFileHandle,
ULONG OptionFlags,
PPATCH_OPTION_DATA OptionData
);
Parameters
OldFileHandle
Handle to the source file.
NewFileHandle
Handle to the target file.
PatchFileHandle
Handle to the delta that is created.
OptionFlags
Creation Flags.
Return Values
Returns TRUE on success or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in patchapi.h |
| DLL | Requires mspatchc.dll |
| Unicode | Not applicable |
See Also
- CreatePatchFile
- CreatePatchFileByHandlesEx
- CreatePatchFileEx
CreatePatchFileExA/W
The CreatePatchFileExA and CreatePatchFileExW functions create a delta between the specified source file and the specified target file. Both the source and the target files are provided as paths. The output delta is also written to a provided path. These functions provide progress reporting during the Create process.
BOOL PATCHAPI CreatePatchFileExA(
ULONG OldFileCount,
PPATCH_OLD_FILE_INFO_A OldFileInfoArray,
LPCTSTR NewFileName,
LPCTSTR PatchFileName,
ULONG OptionFlags,
PPATCH_OPTION_DATA OptionData,
PPATCH_PROGRESS_CALLBACK ProgressCallback,
PVOID CallbackContext
);
BOOL PATCHAPI CreatePatchFileExW(
ULONG OldFileCount,
PPATCH_OLD_FILE_INFO_A OldFileInfoArray,
LPCWSTR NewFileName,
LPCWSTR PatchFileName,
ULONG OptionFlags,
PPATCH_OPTION_DATA OptionData,
PPATCH_PROGRESS_CALLBACK ProgressCallback,
PVOID CallbackContext
);
Parameters
OldFileCount
The total number of source files. Used to create deltas against multiple source files (maximum 255). See Creating Deltas from Multiple Source Files.
OldFileInfoArray
Pointer to source file information array (see Ignore and Retain Ranges in Source files).
NewFileName
The name of the target file.
PatchFileName
The name of the delta that is created.
OptionFlags
Creation Flags.
ProgressCallback
Pointer to application-defined Progress Callback.
CallbackContext
Pointer to application-defined context (see Progress Callback).
Return Values
Returns TRUE on success or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in patchapi.h |
| DLL | Requires mspatchc.dll |
| Unicode | Implemented as CreatePatchFileExW (Unicode) and CreatePatchFileExA (ANSI) |
See Also
- CreatePatchFileEx
- CreatePatchFileByHandles
- CreatePatchFileByHandlesEx
CreatePatchFileByHandlesEx
The CreatePatchFileByHandlesEx function creates a delta between the specified source file and the specified target file. Both the source and the target file are provided as file handles. The output delta is also written to a provided file handle. 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
);
Parameters
OldFileCount
The total number of source files. Used to create deltas against multiple source files (maximum 255). See Creating Deltas from Multiple Source Files.
OldFileInfoArray
Pointer to source file information array (see Ignore and Retain Ranges in Source Files).
NewFileName
Handle to the target file.
PatchFileName
Handle to the delta that is created.
OptionFlags
Creation Flags.
ProgressCallback
Pointer to application-defined Progress Callback.
CallbackContext
Pointer to application-defined context (see Progress Callback).
Return Values
Returns TRUE on success or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in patchapi.h |
| DLL | Requires mspatchc.dll |
| Unicode | Not applicable |
See Also
- CreatePatchFile
- CreatePatchFileByHandles
- CreatePatchFileEx
ApplyPatchToFileA/W
The ApplyPatchToFileA and ApplyPatchToFileW functions apply the specified delta to the specified source file. The output file is saved under the designated new file name.
BOOL PATCHAPI ApplyPatchToFileA(
LPCTSTR PatchFileName,
LPCTSTR OldFileName,
LPCTSTR NewFileName,
ULONG ApplyOptionFlags
);
BOOL PATCHAPI ApplyPatchToFileW(
LPCWSTR PatchFileName,
LPCWSTR OldFileName,
LPCWSTR NewFileName,
ULONG ApplyOptionFlags
);
Parameters
PatchFileName
The name of the delta to be applied to the source file.
OldFileName
The name of the source file to which the delta is to be applied.
NewFileName
The name of the target file that is to be created.
ApplyOptionFlags
ApplyPatch Flags.
Return Values
Returns TRUE on success or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in patchapi.h |
| DLL | Requires mspatcha.dll |
| Unicode | Implemented as ApplyPatchToFileW (Unicode) and ApplyPatchToFileA (ANSI) |
See Also
- ApplyPatchToFileByBuffers
- ApplyPatchToFileByHandles
- ApplyPatchToFileByHandlesEx
- ApplyPatchToFileEx
ApplyPatchToFileByHandles
The ApplyPatchToFileByHandles function applies the specified delta to the specified source file. Both the delta and the source file are provided as file handles. The output data is also written to a provided file handle.
BOOL PATCHAPI ApplyPatchToFileByHandles(
HANDLE PatchFileHandle,
HANDLE OldFileHandle,
HANDLE NewFileHandle,
ULONG ApplyOptionFlags
);
Parameters
PatchFileHandle
Handle to the delta to be applied to the source file. Requires GENERIC_READ access.
OldFileHandle
Optional. Handle to the source file to which the delta is to be applied. Requires GENERIC_READ access.
NewFileHandle
Handle to the target file that is to be created. Requires GENERIC_READ | GENERIC_WRITE.
ApplyOptionFlags
ApplyPatch Flags.
Return Values
Returns TRUE on success or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in patchapi.h |
| DLL | Requires mspatcha.dll |
| Unicode | Not applicable |
See Also
- ApplyPatchToFile
- ApplyPatchToFileByHandlesEx
- ApplyPatchToFileEx
ApplyPatchToFileByBuffers
The ApplyPatchToFileByBuffers function applies the specified delta to the specified source file. Both the delta and the source file are provided as pointers to pre-allocated buffers. The output data is also written into a provided buffer. This function provides progress reporting during the apply process.
BOOL PATCHAPI ApplyPatchToFileByBuffers(
PBYTE PatchFileMapped,
ULONG PatchFileSize,
PBYTE OldFileMapped,
ULONG OldFileSize,
PBYTE* NewFileBuffer,
ULONG NewFileBufferSize,
ULONG* NewFileActualSize,
FILETIME* NewFileTime,
ULONG ApplyOptionFlags,
PPATCH_PROGRESS_CALLBACK ProgressCallback,
PVOID CallbackContext
);
Parameters
PatchFileMapped
Pointer to a buffer containing the delta to be applied to the source.
PatchFileSize
Size of the delta buffer in bytes.
OldFileMapped
Pointer to a buffer containing the source.
OldFileSize
Size of the source buffer in bytes.
NewFileBuffer
Pointer to a buffer where the target should be created. If *NewFileBuffer is NULL, and APPLY_OPTION_TEST_ONLY is not specified, and the function succeeds (returns TRUE), and size of new file is non-zero, *NewFileBuffer will be set to a VirtualAlloc buffer of the required size, and it will be the caller's responsibility to VirtualFree this buffer. NewFileBufferSize is ignored when *NewFileBuffer is NULL.
NewFileBufferSize
Size of the target buffer in bytes. If *NewFileBuffer is non-NULL, and APPLY_OPTION_TEST_ONLY is not specified, NewFileBufferSize specifies the size of caller-supplied *NewFileBuffer buffer. If required size exceeds NewFileBufferSize, function will fail (return FALSE), *NewFileActualSize will be set to required size, and GetLastError will return ERROR_INSUFFICIENT_BUFFER.
NewFileActualSize
Size of the actual target created in bytes. If ApplyOptionFlags APPLY_OPTION_TEST_ONLY is specified, NewFileBuffer and NewFileBufferSize are ignored, and *NewFileActualSize will be set to required buffer size. If APPLY_OPTION_TEST_ONLY is not specified, then NewFileBuffer must be non-NULL (*NewFileBuffer may be NULL).
NewFileTime
Optional. If non-NULL, the value returned will either be non-zero to indicate the new file time as specified in the patch, or zero to indicate that file time was not stored inside the patch.
ApplyOptionFlags
ApplyPatch Flags.
ProgressCallback
Pointer to application-defined Progress Callback. CallbackContext
Pointer to application-defined context (see Progress Callback).
Return Values
Returns TRUE on success or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in patchapi.h |
| DLL | Requires mspatcha.dll |
| Unicode | Not applicable |
See Also
- ApplyPatchToFile
- ApplyPatchToFileByHandles
- ApplyPatchToFileEx
ApplyPatchToFileExA/W
The ApplyPatchToFileExA and ApplyPatchToFileExW functions apply the specified delta to the specified source file. The output file is saved under the designated new file name. These functions provide progress reporting during the apply process.
BOOL PATCHAPI ApplyPatchToFileExA(
LPCTSTR PatchFileName,
LPCTSTR OldFileName,
LPCTSTR NewFileName,
ULONG ApplyOptionFlags,
PPATCH_PROGRESS_CALLBACK ProgressCallback,
PVOID CallbackContext
);
BOOL PATCHAPI ApplyPatchToFileExW(
LPCWSTR PatchFileName,
LPCWSTR OldFileName,
LPCWSTR NewFileName,
ULONG ApplyOptionFlags
PPATCH_PROGRESS_CALLBACK ProgressCallback,
PVOID CallbackContext
);
Parameters
PatchFileName
The name of the delta to be applied to the source file.
OldFileName
The name of the source file to which the delta is to be applied.
NewFileName
The name of the target file that is to be created.
ApplyOptionFlags
ApplyPatch Flags.
ProgressCallback
Pointer to application-defined Progress Callback.
CallbackContext
Pointer to application-defined context (see Progress Callback).
Return Values
Returns TRUE on success or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in patchapi.h |
| DLL | Requires mspatcha.dll |
| Unicode | Implemented as ApplyPatchToFileExW (Unicode) and ApplyPatchToFileExA (ANSI) |
See Also
- ApplyPatchToFile
- ApplyPatchToFileByHandles
- ApplyPatchToFileByHandlesEx
ApplyPatchToFileByHandlesEx
The ApplyPatchToFileByHandlesEx function applies the specified delta to the specified source file. Both the delta and the source file are provided as file handles. The output data is also written to a provided file handle. 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
);
Parameters
PatchFileHandle
Handle to the delta to be applied to the source file. Requires GENERIC_READ access.
OldFileHandle
Optional. Handle to the source 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
ApplyPatch Flags.
ProgressCallback
Pointer to application-defined Progress Callback.
CallbackContext
Pointer to application-defined context (see Progress Callback).
Return Values
Returns TRUE on success or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in patchapi.h |
| DLL | Requires mspatcha.dll |
| Unicode | Not applicable |
See Also
- ApplyPatchToFile
- ApplyPatchToFileByHandles
- ApplyPatchToFileEx
TestApplyPatchToFileA/W
The TestApplyPatchToFileA and TestApplyPatchToFileW functions verify that a specified delta or delta header matches the specified source file. The delta and source files are specified as paths. These functions do not actually apply the delta.
BOOL PATCHAPI TestApplyPatchToFileA(
LPCTSTR PatchFileName,
LPCTSTR OldFileName,
ULONG ApplyOptionFlags
);
BOOL PATCHAPI TestApplyPatchToFileW(
LPCWSTR PatchFileName,
LPCWSTR OldFileName,
ULONG ApplyOptionFlags
);
Parameters
PatchFileName
The name of the delta to check against the source file.
OldFileName
The name of the source file against which the delta is checked.
ApplyOptionFlags
Apply Flags.
Return Values
Returns TRUE if the delta matches the source file or FALSE otherwise. See also Error Codes.
Requirements
| 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 specified delta or delta header matches the specified source file. The delta and source files are specified as handles. This function does not actually apply the delta.
BOOL PATCHAPI TestApplyPatchToFileByHandles(
HANDLE PatchFileHandle,
HANDLE OldFileHandle,
ULONG ApplyOptionFlags
);
Parameters
PatchFileHandle
Handle to the delta. Requires GENERIC_READ access.
OldFileHandle
Handle to the source file to be checked against the delta. Requires GENERIC_READ access.
ApplyOptionFlags
ApplyPatch Flags
Return Values
Returns TRUE if the delta matches the source file or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in patchapi.h |
| DLL | Requires mspatcha.dll |
| Unicode | Not applicable |
See Also
- TestApplyPatchToFile
TestApplyPatchToFileByBuffers
The ApplyPatchToFileByBuffers function verifies that a specified delta or delta header matches the specified source. The delta and source are specified as pre-allocated buffers. This function does not actually apply the delta.
BOOL PATCHAPI TestApplyPatchToFileByBuffers(
PBYTE PatchFileBuffer,
ULONG PatchFileSize,
PBYTE OldFileBuffer,
ULONG OldFileSize,
ULONG* NewFileSize,
ULONG ApplyOptionFlags,
);
Parameters
PatchFileBuffer
Pointer to the buffer containing the delta to be checked against the source.
PatchFileSize
Size of the delta buffer in bytes.
OldFileBuffer
Pointer to the buffer containing the source against which the delta is checked.
OldFileSize
Size of the source buffer in bytes.
NewFileSize
Size of the target that would be produced after applying this delta to the source.
ApplyOptionFlags
Apply Flags.
Return Values
Returns TRUE on success or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in patchapi.h |
| DLL | Requires mspatcha.dll |
| Unicode | Not applicable |
See Also
- ApplyPatchToFile
- ApplyPatchToFileByHandles
- ApplyPatchToFileEx
ExtractPatchHeaderToFileA/W
The ExtractPatchHeaderToFileA and ExtractPatchHeaderToFileW functions extract the header information from a delta. The delta is provided as a file path. The output header is also written to a provided path.
BOOL PATCHAPI ExtractPatchHeaderToFileA(
LPCTSTR PatchFileName,
LPCTSTR PatchHeaderFileName
);
BOOL PATCHAPI ExtractPatchHeaderToFileW(
LPCWSTR PatchFileName,
LPCWSTR PatchHeaderFileName
);
Parameters
PatchFileName
The name of the delta containing the header.
PatchHeaderFileName
The name of the header file that is to be created.
Return Values
Returns TRUE on success or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in patchapi.h |
| DLL | Requires mspatchc.dll |
| Unicode | Implemented as ExtractPatchHeaderToFileW (Unicode) and ExtractPatchHeaderToFileA (ANSI) |
See Also
- ExtractPatchHeaderToFileByHandles
ExtractPatchHeaderToFileByHandles
The ExtractPatchHeaderToFileByHandles function extracts the header information from a delta. The delta is provided as a file handle. The output header is also written to a provided handle.
BOOL PATCHAPI ExtractPatchHeaderToFileByHandles(
HANDLE PatchFileHandle,
HANDLE PatchHeaderFileHandle
);
Parameters
PatchFileName
Handle to the delta containing the header.
PatchHeaderFileName
Handle to the header file that is to be created.
Return Values
Returns TRUE on success or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in patchapi.h |
| DLL | Requires mspatchc.dll |
| Unicode | Not applicable |
See Also
- ExtractPatchHeaderToFile
GetFilePatchSignatureA/W
The GetFilePatchSignatureA and GetFilePatchSignatureW functions calculate a normalized signature for the specified file and write it to a specified buffer. This signature can be used to locate potential delta source files for a delta.
BOOL PATCHAPI GetFilePatchSignatureA(
LPCTSTR FileName,
ULONG OptionFlags,
PVOID OptionData,
ULONG IgnoreRangeCount,
PPATCH_IGNORE_RANGE IgnoreRangeArray,
ULONG RetainRangeCount,
PPATCH_RETAIN_RANGE RetainRangeArray,
ULONG SignatureBufferSize,
PVOID SignatureBuffer
);
BOOL PATCHAPI GetFilePatchSignatureW(
LPCWSTR FileName,
ULONG OptionFlags,
PVOID OptionData,
ULONG IgnoreRangeCount,
PPATCH_IGNORE_RANGE IgnoreRangeArray,
ULONG RetainRangeCount,
PPATCH_RETAIN_RANGE RetainRangeArray,
ULONG SignatureBufferSize,
PVOID SignatureBuffer
);
Parameters
FileName
Name of the file for which the normalized signature is to be generated.
OptionFlags
Get Signature Flags.
OptionData
Not used. Pass NULL. Pointer to a structure of type PATCH_OPTION_DATA.
IgnoreRangeCount
The total number of Ignore Ranges in the File.
IgnoreRangeArray
Pointer to the structure that defines the ignore range (see Ignore and Retain Ranges in Source files).
RetainRangeCount
The total number of Retain Ranges in the File.
RetainRangeArray
Pointer to the structure that defines the retain range (see Ignore and Retain Ranges in Source files).
SignatureBufferSize
Size of signature buffer.
SignatureBuffer
Pointer to the caller-allocated buffer that will contain the signature.
Return Values
Returns TRUE on success or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in patchapi.h |
| DLL | Requires mspatcha.dll or mspatchc.dll |
| Unicode | Implemented as GetFilePatchSignatureW (Unicode) and GetFilePatchSignatureA (ANSI). |
See Also
- GetFilePatchSignatureByHandle
- GetFilePatchSignatureByBuffer
- NormalizeFileForPatchSignature
GetFilePatchSignatureByHandle
The GetFilePatchSignatureByHandle calculates a normalized signature for the specified file (specified by a handle) and writes it to a specified buffer. This signature can be used to locate potential delta source files for a delta.
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
);
Parameters
FileHandle
Handle to the file for which the signature is to be generated.
OptionFlags
Get Signature Flags.
OptionData
Not used. Pointer to a structure of type PATCH_OPTION_DATA.
IgnoreRangeCount
The total number of Ignore Ranges in the File.
IgnoreRangeArray
Pointer to the structure that defines the ignore range (see Ignore and Retain Ranges in Source files).
RetainRangeCount
The total number of Retain Ranges in the File.
RetainRangeArray
Pointer to the structure that defines the retain range (see Ignore and Retain Ranges in Source files).
SignatureBufferSize
Size of signature buffer.
SignatureBuffer
Pointer to the caller-allocated buffer that will contain the signature.
Return Values
Returns TRUE on success or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in patchapi.h |
| DLL | Requires mspatcha.dll or mspatchc.dll |
| Unicode | Not applicable |
See Also
- GetFilePatchSignature
- GetFilePatchSignatureByBuffer
- NormalizeFileForPatchSignature
GetFilePatchSignatureByBuffer
The GetFilePatchSignatureByBuffer calculates a normalized signature for the specified file (provided in a buffer) and writes it to a specified buffer. This signature can be used to locate potential delta source files for a delta.
BOOL PATCHAPI GetFilePatchSignatureByHandle(
PBYTE FileBufferWritable,
ULONG FileSize,
ULONG OptionFlags,
PVOID OptionData,
ULONG IgnoreRangeCount,
PPATCH_IGNORE_RANGE IgnoreRangeArray,
ULONG RetainRangeCount,
PPATCH_RETAIN_RANGE RetainRangeArray,
ULONG SignatureBufferSize,
PVOID SignatureBuffer
);
Parameters
FileBufferWritable
Pointer to the caller-allocated buffer containing the contents of the file for which the signature is to be generated. This buffer will be modified by PatchAPI, and its contents will be unreliable after this call.
FileSize
Count of bytes in FileBufferWritable.
OptionFlags
Get Signature Flags.
OptionData
Not used. Pointer to a structure of type PATCH_OPTION_DATA.
IgnoreRangeCount
The total number of Ignore Ranges in the File.
IgnoreRangeArray
Pointer to the structure that defines the ignore range (see Ignore and Retain Ranges in Source files).
RetainRangeCount
The total number of Retain Ranges in the File.
RetainRangeArray
Pointer to the structure that defines the retain range (see Ignore and Retain Ranges in Source files).
SignatureBufferSize
Size of signature buffer.
SignatureBuffer
Pointer to the caller-allocated buffer that will contain the signature.
Return Values
Returns TRUE on success or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in patchapi.h |
| DLL | Requires mspatcha.dll or mspatchc.dll |
| Unicode | Not applicable |
See Also
- GetFilePatchSignature
- GetFilePatchSignatureByHandle
- NormalizeFileForPatchSignature
NormalizeFileForPatchSignature
The NormalizeFileForPatchSignature function performs the same normalization as the GetFilePatchSignature functions on a given buffer, without calculating a signature. This may be useful if a caller wishes to use a hashing routine that is not supported by the PatchAPI.
BOOL WINAPI NormalizeFileForPatchSignature (
PVOID FileBuffer,
ULONG FileSize,
ULONG OptionFlags,
PATCH_OPTION_DATA* OptionData,
ULONG NewFileCoffBase,
ULONG NewFileCoffTime,
ULONG IgnoreRangeCount,
PPATCH_IGNORE_RANGE IgnoreRangeArray,
ULONG RetainRangeCount,
PPATCH_RETAIN_RANGE RetainRangeArray
);
Parameters
FileBuffer
The buffer containing the file to be normalized.
FileSize
The size of the file to be normalized.
OptionFlags
Get Signature Flags.
OptionData
Not used. Pointer to a structure of type PATCH_OPTION_DATA.
NewFileCoffBase
PE base address. The file being normalized is rebased to this address if it is PE and if OptionFlags don't override this behavior.
NewFileCoffTime
PE header timestamp. This timestamp value is to be written into the normalized file's header if it is PE and if OptionFlags don't override this behavior.
IgnoreRangeCount
The total number of Ignore Ranges in the File.
IgnoreRangeArray
Pointer to the structure that defines the ignore range (see Ignore and Retain Ranges in Source files).
RetainRangeCount
The total number of Retain Ranges in the File.
RetainRangeArray
Pointer to the structure that defines the retain range (see Ignore and Retain Ranges in Source files).
Return Values
Returns 0 on failure.
Returns 1 to indicate that the buffer did not require normalization.
Returns 2 to indicate successful normalization.
See also Error Codes.
Requirements
| Header | Declared in patchapi.h |
| DLL | Requires mspatcha.dll or mspatchc.dll |
| Unicode | Not applicable |
See Also
- GetFilePatchSignature
- GetFilePatchSignatureByHandle
- GetFilePatchSignatureByBuffer
MSDelta
Microsoft Corporation
October 2009
Purpose
MSDelta is a differential compression library that can create much smaller compressed files than those produced by other methods. Shipping with Windows Vista, it is the next generation of the technology previously released as PatchAPI (which will continue to be supported). MSDelta will be used to compress updates for Windows Vista, Windows Server 2008, Windows 7, and Windows 2008 R2, and in other scenarios.
Applies to:
Microsoft® Windows Vista®
Windows Server 2008®
Windows 7®
Windows Server 2008 R2®
Getting MSDelta Components
MSDelta includes the following files:
- msdelta.dll: Dynamic link library for creating and applying deltas. This library is shipped with Windows Vista, Windows Server 2008, Windows 7, and Windows 2008 R2. It can be found in the System32 directory.
- msdelta.h: Header file that defines the API functions, structures, and constants. This header is part of the current version of Windows Platform SDK.
Run-Time Requirements
MSDelta requires significant memory resources during delta Create operations, but is more efficient during delta Apply. The following table summarizes the run-time memory requirements:
| Process | Estimated Maximum Memory Usage (MB) |
|---|---|
| CreateDelta | 10.2 * ( SourceSize + TargetSize ) + 2.7 |
| ApplyDelta | 2 * SourceSize + TargetSize + 3.7 |
| DeltaSignature | 2 * SourceSize + 2.7 |
Topics in This Section
- What's New in MSDelta
- MSDelta Reference
What's New in MSDelta
Microsoft Corporation
July 2013
MSDelta is the next generation of the Delta Compression technology previously released as PatchAPI (which will continue to be supported). MSDelta adds value beyond PatchAPI in the following ways:
- While PatchAPI offered specialized handling only for i386 executable files, MSDelta includes special handling for ia64, amd64, ARM and MSIL formats. This allows for much smaller deltas than would be possible without optimization for these file types.
See also File Type Sets. - PatchAPI was used in very limited scenarios, mainly to service the Windows operating system and as part of the Windows Installer MSP file format. MSDelta will be made available to third-party developers for exciting new applications.
- The MSDelta API is much simpler than PatchAPI, and therefore easier to use.
- MSDelta now supports ARM-based processors and has been updated to better support compiled .NET assemblies and executables.
File Type Sets
The delta Create process can be optimized by making allowances for embedded pointers and volatile elements. This special handling is determined by the file type of the input files.
MSDelta automatically detects the file type of the input files based on the specified File type set. This enables MSDelta to create smaller deltas under some conditions.
The valid file type sets are DELTA_FILE_TYPE_SET_RAW_ONLY, DELTA_FILE_TYPE_SET_EXECUTABLES_1, DELTA_FILE_TYPE_SET_EXECUTABLES_2, and DELTA_FILE_TYPE_SET_EXECUTABLES_LATEST.
Specifying DELTA_FILE_TYPE_SET_RAW_ONLY causes MSDelta to treat all sources as raw files only. No special handling is performed.
Specifying DELTA_FILE_TYPE_SET_EXECUTABLES_1, DELTA_FILE_TYPE_SET_EXECUTABLES_2, or DELTA_FILE_TYPE_SET_EXECUTABLES_LATEST causes MSDelta to detect whether the input files are of a file format for which MSDelta supports special handling. Valid deltas are created for any input data, but the special handling for certain file types enables MSDelta to create smaller deltas for them.
The following table lists the file types along with descriptions.
| File Type (Constant) | Description |
|---|---|
| DELTA_FILE_TYPE_RAW_ONLY | Raw file type. |
| DELTA_FILE_TYPE_I386 | File type for Intel x386 (I386) Portable Executable (PE) files. |
| DELTA_FILE_TYPE_IA64 | File type for Intel Itanium (IA64) Portable Executable (PE) files. |
| DELTA_FILE_TYPE_AMD64 | File type for AMD 64-bit (AMD64) Portable Executable (PE) files. |
| DELTA_FILE_TYPE_ARM | File type for ARM Portable Executable (PE) files. |
| DELTA_FILE_TYPE_SET_EXECUTABLES_1 | File type set that includes I386, IA64 and AMD64 Portable Executable (PE) files. Others are treated as raw. |
| DELTA_FILE_TYPE_SET_EXECUTABLES_2 | File type set that includes I386, IA64, AMD64, and ARM portable Executable (PE) files using improved CLI4 compression. Others are treated as raw. |
| DELTA_FILE_TYPE_SET_EXECUTABLES_LATEST | Provides the latest transforms and the largest set of non-raw file types. |
The following two environment variables have the same capabilities as variables in the above table. They provide compatibility with existing applications.
| File Type (Constant) | Description |
|---|---|
| DELTA_FILE_TYPE_SET_RAW | Same as DELTA_FILE_TYPE_RAW_ONLY. |
| DELTA_FILE_TYPE_SET_EXECUTABLES | Same as DELTA_FILE_TYPE_SET_EXECUTABLES_1. |
The following table lists the default Flags used during the Create process for the various file type sets.
| File Type | Default Flags |
|---|---|
| RAW | DELTA_FLAG_NONE |
| Intel (I386) | DELTA_FLAG_MARK DELTA_FLAG_IMPORTS DELTA_FLAG_EXPORTS DELTA_FLAG_RESOURCES DELTA_FLAG_RELOCS DELTA_FLAG_I386_SMASHLOCK DELTA_FLAG_I386_JMPS DELTA_FLAG_I386_CALLS DELTA_FLAG_UNBIND DELTA_FLAG_CLI_DISASM DELTA_FLAG_CLI_METADATA |
| Intel Itanium (IA64) | DELTA_FLAG_MARK DELTA_FLAG_IMPORTS DELTA_FLAG_EXPORTS DELTA_FLAG_RESOURCES DELTA_FLAG_RELOCS DELTA_FLAG_IA64_DISASM DELTA_FLAG_IA64_PDATA DELTA_FLAG_UNBIND DELTA_FLAG_CLI_DISASM DELTA_FLAG_CLI_METADATA |
| AMD 64 (AMD64) | DELTA_FLAG_MARK DELTA_FLAG_IMPORTS DELTA_FLAG_EXPORTS DELTA_FLAG_RESOURCES DELTA_FLAG_RELOCS DELTA_FLAG_AMD64_DISASM DELTA_FLAG_AMD64_PDATA DELTA_FLAG_UNBIND DELTA_FLAG_CLI_DISASM DELTA_FLAG_CLI_METADATA |
| Intel (I386) using improved CLI4 compression | DELTA_FLAG_MARK DELTA_FLAG_IMPORTS DELTA_FLAG_EXPORTS DELTA_FLAG_RESOURCES DELTA_FLAG_RELOCS DELTA_FLAG_AMD64_DISASM DELTA_FLAG_AMD64_PDATA DELTA_FLAG_CLI4_UNBIND DELTA_FLAG_CLI4_DISASM DELTA_FLAG_CLI4_METADATA |
| AMD 64 (AMD64) using improved CLI4 compression | DELTA_FLAG_MARK DELTA_FLAG_IMPORTS DELTA_FLAG_EXPORTS DELTA_FLAG_RESOURCES DELTA_FLAG_RELOCS DELTA_FLAG_AMD64_DISASM DELTA_FLAG_AMD64_PDATA DELTA_FLAG_CLI4_UNBIND DELTA_FLAG_CLI4_DISASM DELTA_FLAG_CLI4_METADATA |
| ARM | DELTA_FLAG_MARK DELTA_FLAG_IMPORTS DELTA_FLAG_EXPORTS DELTA_FLAG_RESOURCES DELTA_FLAG_RELOCS DELTA_FLAG_AMD64_DISASM DELTA_FLAG_AMD64_PDATA DELTA_FLAG_CLI4_UNBIND DELTA_FLAG_CLI4_DISASM DELTA_FLAG_CLI4_METADATA |
Delta Parameters
This section describes the different structures and flags defined in msdelta.h.
Create Parameters
| Parameter | Description |
|---|---|
| DELTA_FLAGS_TYPE Flags | Optional flags used to define specific handling or operations. |
| DELTA_INPUT | Structure for input buffers. |
| DELTA_OUTPUT | Structure for output buffers.
These buffers must be freed using DeltaFree after use. |
| DELTA_HEADER_INFO | Structure used to access information stored in the delta header. |
| DELTA_HASH | Structure used to represent signatures. |
Delta Input Structure
The following structure defines the format for input buffers used by MSDelta.
typedef struct _DELTA_INPUT
{
union{
LPCVOID lpcStart;
LPVOID lpStart;
};
SIZE_T uSize;
BOOL Editable;
} DELTA_INPUT;
Members
lpcStart
Memory address of the beginning of editable input buffer.
lpStart
Memory address non-editable input buffer.
uSize
Size of the memory buffer in bytes.
Editable
Defines whether MSDelta is allowed to edit the input buffer. If you make the input editable, the buffer will be zeroed at function return. However this will cause most MSDelta functions to use less memory.
Delta Output Structure
The following structure defines the format for output buffers used by MSDelta.
Note: You must free any defined DELTA_OUTPUT buffers by using DeltaFree after use.
typedef struct _DELTA_OUTPUT
{
LPVOID lpStart;
SIZE_T uSize;
} DELTA_OUTPUT;
Members
lpStart
Memory address of the beginning of buffer.
uSize
Size of the memory buffer in bytes.
Delta Information Structure
The following structure defines the format of information as it is returned after extraction from the delta header.
typedef struct _DELTA_HEADER_INFO
{
DELTA_FILE_TYPE FileTypeSet;
DELTA_FILE_TYPE FileType;
DELTA_FLAG_TYPE Flags;
SIZE_T TargetSize;
FILETIME TargetFileTime;
ALG_ID TargetHashAlgId;
DELTA_HASH TargetHash;
} DELTA_HEADER_INFO;
Members
FileTypeSet
The file type set used during Create, which will also be used during the Apply process. See also File Type Sets.
FileType
The specific file type of the source file. See also File Type Sets.
Flags
The flags used during Create, which will also be used during the Apply process. See also Flags.
TargetSize
The size of the target in bytes.
TargetFileTime
The time stamp for the target.
TargetHashAlgId
ALG_ID of the algorithm that was used to generate the target signature. Some special values are:
0 = No signature.
32 = 32-bit CRC defined in msdelta.dll.
TargetHash
The target signature.
Delta Hash Structure
The following structure defines the manner in which signatures are represented in MSDelta.
typedef struct _DELTA_HASH
{
DWORD HashSize ;
UCHAR HashValue[ DELTA_MAX_HASH_SIZE ];
} DELTA_HASH;
Members
HashSize
The size of the signature in bytes. Cannot exceed 32 bytes.
HashValue
The signature value.
DELTA_FLAG_TYPE Flags
The following tables list the flags that can be combined and supplied to MSDelta functions. These options mainly include specific transform instructions (special handling for supported file types). Since the same preprocessing needs to be carried out on delta apply, these flags are encoded into the delta as well. The GetDeltaInfo functions extract the flags as well as other information from the delta.
Delta Apply Flags
| Flag | Description |
|---|---|
| DELTA_FLAG_NONE | Indicates no special handling. |
| DELTA_APPLY_FLAG_ALLOW_PA19 | Allow MSDelta to apply deltas created using PatchAPI. |
Delta Create Flags
| Flag | Description |
|---|---|
| DELTA_FLAG_NONE | Indicates no special handling. |
| DELTA_FLAG_MARK | Marks certain regions of the source file as "definitely-not-executable" to prevent some of the false positives in the I386_JMPS and I386_CALLS transformations. |
| DELTA_FLAG_IMPORTS | Transform the imports associated with the source PE file. |
| DELTA_FLAG_EXPORTS | Transform the exports associated with the source PE file. |
| DELTA_FLAG_RESOURCES | Transform the resources associated with the source PE file. |
| DELTA_FLAG_RELOCS | Transform the relocations of the source PE file. |
| DELTA_FLAG_I386_SMASHLOCK | Repair any smashed lock prefixes in the source PE file. |
| DELTA_FLAG_I386_JMPS | Transform the relative jumps in the source I386 PE file. |
| DELTA_FLAG_I386_CALLS | Transform the relative calls embedded within the source I386 PE file. |
| DELTA_FLAG_AMD64_DISASM | Transform the instructions of the source AMD64 PE file. |
| DELTA_FLAG_AMD64_PDATA | Transform the pdata of the source AMD64 PE file. |
| DELTA_FLAG_IA64_DISASM | Transform the instructions of the source AMD64 PE file. |
| DELTA_FLAG_IA64_PDATA | Transform the pdata of the source IA64 PE file. |
| DELTA_FLAG_UNBIND | Unbind the source PE file. |
| DELTA_FLAG_CLI_DISASM | Transform the CLI instructions of the source PE file. |
| DELTA_FLAG_CLI_METADATA | Transform the CLI metadata of the source PE file. |
| DELTA_FLAG_HEADERS | Transform the headers of the source PE file. |
| DELTA_FLAG_IGNORE_FILE_SIZE_LIMIT | Allow the source, target and delta files to exceed the default size limit. |
| DELTA_FLAG_IGNORE_OPTIONS_SIZE_LIMIT | Allow the options buffer or files to exceed the default size limit. |
| DELTA_FLAG_E8 | Transform E8 instructions (relative calls) of the target file.
Note: If this flag is neither set nor reset during Create, MSDelta will create the delta twice – once with the flag set and once with it reset. The smaller of the two deltas will be returned. |
| DELTA_FLAG_ARM_DISASM | Transform the instructions of the source ARM PE file. |
| DELTA_FLAG_ARM_PDATA | Transform the pdata of the source ARM PE file. |
| DELTA_FLAG_CLI4_METADATA | Transform the CLI metadata of the source PE file. |
| DELTA_FLAG_CLI4_DISASM | Transform the CLI instructions of the source PE file. |
| DELTA_FLAG_CLI4_UNBIND | Unbind the source PE file. |
| DELTA_CLI4_FLAGS_I386 | Sets the file type as Intel x386 (i386) portable execution file using CLI4 compression. |
| DELTA_CLI4_FLAGS_ARM | Sets the file type as ARM portable execution file using CLI4 compression. |
| DELTA_CLI4_FLAGS_AMD64 | Sets the file type as AMD 64-bit portable execution file using CLI4 compression. |
MSDelta Error Codes
When an MSDelta function returns FALSE, you can call GetLastError to get the corresponding Win32 system error code.
For more information, see the WINERROR.H documentation on MSDN.
MSDelta Reference
Microsoft Corporation
October 2009
The tables below list the MSDelta functions grouped by the following categories.
- Create Delta Functions
- Apply Delta Functions
- Extract Delta Information Functions
- Get Normalized Signature Functions
- Other Functions
Note: The header file msdelta.h uses the -A suffix to identify functions that take ANSI arguments and the –W suffix to identify functions that take UNICODE arguments. To simplify usage the un-suffixed function name is conditionally redefined as the appropriate suffixed function name depending on whether UNICODE is defined or not at compile time. For example, if UNICODE is defined, CreateDelta is defined as CreateDeltaW.
Create Deltas
| Functions | Description |
|---|---|
| CreateDeltaA
CreateDeltaW CreateDeltaB |
Create deltas. |
Apply Deltas
| Functions | Description |
|---|---|
| ApplyDeltaA
ApplyDeltaW ApplyDeltaB ApplyDeltaProvidedB |
Apply deltas. |
Extract Delta Information
| Functions | Description |
|---|---|
| GetDeltaInfoA
GetDeltaInfoW GetDeltaInfoB |
Extract information from deltas. |
Get Signatures
| Functions | Description |
|---|---|
| GetDeltaSignatureA
GetDeltaSignatureW GetDeltaSignatureB |
Calculate normalized signatures from files (see Normalized File Signatures). |
| DeltaNormalizeProvidedB | Normalizes the contents of the designated buffer. |
Other Functions
| Functions | Description |
|---|---|
| DeltaFree | Frees the specified MSDelta-allocated memory block. You must call this function after calling CreateDeltaB and ApplyDeltaB. |
See Also
- File Type Sets
Describes the different file type sets for which MSDelta provides special handling. - Delta Structures and Parameters
Describes the structures and flags used by MSDelta. - Error Codes
Describes the error codes returned by the MSDelta engine in the event of failed processes.
CreateDeltaA/W
The CreateDeltaA and CreateDeltaW functions create a delta from the specified source and target files and write the output delta to the designated file name.
Syntax
BOOL WINAPI CreateDeltaA(
DELTA_FILE_TYPE FileTypeSet,
DELTA_FLAG_TYPE SetFlags,
DELTA_FLAG_TYPE ResetFlags,
LPCSTR lpSourceName,
LPCSTR lpTargetName,
LPCSTR lpSourceOptionsName,
LPCSTR lpTargetOptionsName,
DELTA_INPUT GlobalOptions,
const FILETIME *lpTargetFileTime,
ALG_ID HashAlgId,
LPCSTR lpDeltaName
);
BOOL WINAPI CreateDeltaW(
DELTA_FILE_TYPE FileTypeSet,
DELTA_FLAG_TYPE SetFlags,
DELTA_FLAG_TYPE ResetFlags,
LPCWSTR lpSourceName,
LPCWSTR lpTargetName,
LPCWSTR lpSourceOptionsName,
LPCWSTR lpTargetOptionsName,
DELTA_INPUT GlobalOptions,
const FILETIME *lpTargetFileTime,
ALG_ID HashAlgId,
LPCWSTR lpDeltaName
);
Parameters
FileTypeSet
[in] The file type set used for Create. See also File Type Sets.
SetFlags
[in] The Flags to be used during Create, in addition to the default flags.
ResetFlags
[in] The default Flags to be reset during Create.
lpSourceName
[in] The name of the source file to be compared to the target.
lpTargetName
[in] The name of the target against which the source is compared.
lpSourceOptionsName
[in] Reserved. Pass NULL.
lpTargetOptionsName
[in] Reserved. Pass NULL.
GlobalOptions
[in] Reserved. Pass a DELTA_INPUT structure with lpStart set to NULL and uSize set to 0.
lpTargetFileTime
[in] The time stamp set on the target file after delta Apply. If NULL, the timestamp of the target file during delta Create will be used.
HashAlgId
[in] ALG_ID of the algorithm to be used to generate the target signature. Some special values are:
0 = No signature
32 = 32-bit CRC defined in msdelta.dll
lpDeltaName
[in] The name of the delta file to be created.
Return Values
Returns TRUE on success or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in msdelta.h |
| DLL | Requires msdelta.dll |
| Unicode | Implemented as CreateDeltaW createdeltaaw (Unicode) and CreateDeltaA createdeltaaw (ANSI) |
See Also
- CreateDeltaB
- File Type Sets
- Flags
CreateDeltaB
The CreateDeltaB function creates a delta between the source and target (provided as buffers) and returns the output delta as an MSDelta-allocated buffer.
Note: You must call DeltaFree to free the output buffer after this function has completed.
Syntax
BOOL WINAPI CreateDeltaB(
DELTA_FILE_TYPE FileTypeSet,
DELTA_FLAG_TYPE SetFlags,
DELTA_FLAG_TYPE ResetFlags,
DELTA_INPUT Source,
DELTA_INPUT Target,
DELTA_INPUT SourceOptions,
DELTA_INPUT TargetOptions,
DELTA_INPUT GlobalOptions,
const FILETIME *lpTargetFileTime,
ALG_ID HashAlgId,
LPDELTA_OUTPUT lpDelta
);
Parameters
FileTypeSet
[in] The file type set to be used for Create. See also File Type Sets.
SetFlags
[in] The Flags to be used during Create, in addition to the default flags.
ResetFlags
[in] The default Flags to be reset during Create.
Source
[in] DELTA_INPUT structure containing a pointer to the buffer containing the source data.
Target
[in] DELTA_INPUT structure containing a pointer to the buffer containing the target data.
SourceOptions
[in] Reserved. Pass a DELTA_INPUT structure with Editable set to FALSE, lpStart set to NULL and uSize set to 0.
TargetOptions
[in] Reserved. Pass a DELTA_INPUT structure with Editable set to FALSE, lpStart set to NULL and uSize set to 0.
GlobalOptions
[in] Reserved. Pass a DELTA_INPUT structure with lpStart set to NULL and uSize set to 0.
lpTargetFileTime
[in] The time stamp set on the target file after delta Apply. If NULL, the target timestamp will be the current time during Create.
HashAlgId
[in] ALG_ID of the algorithm to be used to generate the target signature. Some special values are:
0 = No signature
32 = 32-bit CRC defined in msdelta.dll
lpDelta
[out] Pointer to the DELTA_OUTPUT structure where the delta is to be written.
Return Values
Returns TRUE on success or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in msdelta.h |
| DLL | Requires msdelta.dll |
| Unicode | Not applicable |
See Also
- CreateDeltaA/W
- DeltaFree
- File Type Sets
- Flags
- DELTA_INPUT
- DELTA_OUTPUT
ApplyDeltaA/W
The ApplyDeltaA and ApplyDeltaW functions use the specified delta and source files to create a new copy of the target file. The output file is saved under the file name, lpTargetName.
Note: If the specified delta was created using PatchAPI, and the DELTA_APPLY_FLAG_ALLOW_PA19 flag is set, MSDelta will call PatchAPI to apply the delta.
Syntax
BOOL WINAPI ApplyDeltaA(
DELTA_FLAG_TYPE ApplyFlags,
LPCSTR lpSourceName,
LPCSTR lpDeltaName,
LPCSTR lpTargetName
);
BOOL WINAPI ApplyDeltaW(
DELTA_FLAG_TYPE ApplyFlags,
LPCWSTR lpSourceName,
LPCWSTR lpDeltaName,
LPCWSTR lpTargetName
);
Parameters
ApplyFlags
[in] Either DELTA_FLAG_NONE or DELTA_APPLY_FLAG_ALLOW_PA19. See also DELTA_FLAG_TYPE flags.
lpSourceName
[in] The name of the source file to which the delta is to be applied.
lpDeltaName
[in] The name of the delta to be applied to the source file.
lpTargetName
[in] The name of the target file that is to be created.
Return Values
Returns TRUE on success or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in msdelta.h |
| DLL | Requires msdelta.dll Requires mspatcha.dll when applying a delta created using PatchAPI. |
| Unicode | Implemented as ApplyDeltaW (Unicode) and ApplyDeltaA (ANSI) |
See Also
- ApplyDeltaB
- ApplyDeltaProvidedB
ApplyDeltaB
The ApplyDeltaB function uses the delta and source (provided as buffers) to create a new copy of the target data. The output data is returned in an MSDelta-allocated buffer.
Note: You must call DeltaFree to free the output buffer after this function has completed.
Note: If the specified delta was created using PatchAPI, and the DELTA_APPLY_FLAG_ALLOW_PA19 flag is set, MSDelta will call PatchAPI to apply the delta.
Syntax
BOOL WINAPI ApplyDeltaB(
DELTA_FLAG_TYPE ApplyFlags,
DELTA_INPUT Source,
DELTA_INPUT Delta,
LPDELTA_OUTPUT lpTarget
);
Parameters
ApplyFlags
[in] Either DELTA_FLAG_NONE or DELTA_APPLY_FLAG_ALLOW_PA19. See also DELTA_FLAG_TYPE flags.
Source
[in] DELTA_INPUT structure containing a pointer to the buffer containing the source data.
Delta
[in] DELTA_INPUT structure containing a pointer to the buffer containing the delta data.
lpTarget
[out] Pointer to the DELTA_OUTPUT structure where the target is to be written.
Return Values
Returns TRUE on success or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in msdelta.h |
| DLL | Requires msdelta.dll Requires mspatcha.dll when applying a delta created using PatchAPI. |
| Unicode | Not applicable |
See Also
- ApplyDeltaA/W
- DeltaFree
- ApplyDeltaProvidedB
- ApplyDeltaB
ApplyDeltaProvidedB
The ApplyDeltaProvidedB function uses the delta and source (specified as caller-allocated buffers) to create the target. The output file is saved to a caller-allocated buffer.
Note: If the specified delta was created using PatchAPI, and the DELTA_APPLY_FLAG_ALLOW_PA19 flag is set, MSDelta will call PatchAPI to apply the delta.
Syntax
BOOL WINAPI ApplyDeltaProvidedB(
DELTA_FLAG_TYPE ApplyFlags,
DELTA_INPUT Source,
DELTA_INPUT Delta,
LPVOID lpTarget,
SIZE_T uTargetSize
);
ApplyFlags
[in] Either DELTA_FLAG_NONE or DELTA_APPLY_FLAG_ALLOW_PA19. See also DELTA_FLAG_TYPE flags.
Source
[in] DELTA_INPUT structure containing a pointer to the buffer containing the source data.
Delta
[in] DELTA_INPUT structure containing a pointer to the buffer containing the delta data.
lpTarget
[in] Pointer to the caller-allocated buffer to which the target output is to be written.
uTargetSize
[in] The size of the memory buffer to which the output is to be written.
Note: This function fails if uTargetSize does not match the actual size of the decompressed Target. This information can be obtained by calling GetDeltaInfo.
Return Values
Returns TRUE on success or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in msdelta.h |
| DLL | Requires msdelta.dll Requires mspatcha.dll when applying a delta created using PatchAPI. |
| Unicode | Not applicable |
See Also
- ApplyDeltaA/W
GetDeltaInfoA/W
The GetDeltaInfoA and GetDeltaInfoW functions retrieve information about a specified delta.
For more information, see also DELTA_HEADER_INFO.
Syntax
BOOL WINAPI GetDeltaInfoA(
LPCSTR lpDeltaName,
LPDELTA_HEADER_INFO lpHeaderInfo
);
BOOL WINAPI GetDeltaInfoW(
LPWCSTR lpDeltaName,
LPDELTA_HEADER_INFO lpHeaderInfo
);
Parameters
lpDeltaName
[in] The name of the delta file from which to extract the information.
lpHeaderInfo
[out] A pointer to the DELTA_HEADER_INFO structure to which the retrieved information is to be written.
Return Values
Returns TRUE on success or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in msdelta.h |
| DLL | Requires msdelta.dll |
| Unicode | Implemented as GetDeltaInfoW (Unicode) and GetDeltaInfoA (ANSI) |
See Also
- GetDeltaInfoB
GetDeltaInfoB
The GetDeltaInfoB function retrieves information about a specified delta.
For more information, see also DELTA_HEADER_INFO.
Syntax
BOOL WINAPI GetDeltaInfoB(
DELTA_INPUT Delta,
LPDELTA_HEADER_INFO lpHeaderInfo
);
Parameters
Delta
[in] DELTA_INPUT structure containing a pointer to the buffer containing the delta.
lpHeaderInfo
[out] A pointer to the DELTA_HEADER_INFO structure to which the retrieved information is to be written.
Return Values
Returns TRUE on success or FALSE otherwise.
See also MSDelta Error Codes.
Requirements
| Header | Declared in msdelta.h |
| DLL | Requires msdelta.dll Requires mspatcha.dll when applying a delta created using PatchAPI. |
| Unicode | Not applicable |
See Also
- GetDeltaInfoA/W
- ApplyDeltaProvidedB
GetDeltaSignatureA/W
The GetDeltaSignatureA and GetDeltaSignatureW functions calculate a normalized signature for the specified file.
Syntax
BOOL WINAPI GetDeltaSignatureA(
DELTA_FILE_TYPE FileTypeSet,
ALG_ID HashAlgId,
LPCSTR lpSourceName,
LPDELTA_HASH lpHash
);
BOOL WINAPI GetDeltaSignatureW(
DELTA_FILE_TYPE FileTypeSet,
ALG_ID HashAlgId,
LPCWSTR lpSourceName,
LPDELTA_HASH lpHash
);
Parameters
FileTypeSet
[in] The file type set to be used for Normalization. See also File Type Sets.
HashAlgId
[in] ALG_ID of the algorithm to use to generate the signature. A special value is:
32 = 32-bit CRC defined in msdelta.dll
Note: 0 = No signature is not supported for this call and will cause MSDelta to return a hash value of all 0s.
lpSourceName
[in] The name of the source file to be hashed.
lpHash
[out] Pointer to the LPDELTA_HASH structure to which the normalized signature is to be written.
Return Values
Returns TRUE on success or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in msdelta.h |
| DLL | Requires msdelta.dll |
| Unicode | Implemented as GetDeltaSignatureW (Unicode) and GetDeltaSignatureA (ANSI). |
See Also
- GetDeltaSignatureB
- DeltaNormalizeProvidedB
GetDeltaSignatureB
The GetDeltaSignatureB function calculates a normalized signature for the specified buffer.
Syntax
BOOL WINAPI GetDeltaSignatureB(
DELTA_FILE_TYPE FileTypeSet,
ALG_ID HashAlgId,
DELTA_INPUT Source,
LPDELTA_HASH lpHash
);
Parameters
FileTypeSet
[in] The file type set to use for Normalization. See also File Type Sets.
HashAlgId
[in] ALG_ID of the algorithm to use to generate the signature. A special value is:
32 = 32-bit CRC defined in msdelta.dll
Note: 0 = No signature is not supported for this call and will cause MSDelta to return a hash value of all 0s.
Source
[in] DELTA_INPUT structure containing a pointer to the buffer containing the source data.
lpHash
[out] Pointer to the LPDELTA_HASH structure to which the normalized signature is to be written.
Return Values
Returns TRUE on success or FALSE otherwise.
See also Error Codes.
Requirements
| Header | Declared in msdelta.h |
| DLL | Requires msdelta.dll |
| Unicode | Not applicable |
See Also
- GetDeltaSignatureA/W
- DeltaNormalizeProvidedB
DeltaNormalizeProvidedB
The DeltaNormalizeProvidedB function normalizes the contents of the source buffer. This is equivalent to the normalization performed by the GetDeltaSignature functions, and may be useful if the caller wishes to perform the signature calculation using an algorithm not supported by MSDelta.
Syntax
BOOL WINAPI DeltaNormalizeProvidedB(
DELTA_FILE_TYPE FileTypeSet,
DELTA_FLAG_TYPE NormalizeFlags,
DELTA_INPUT NormalizeOptions,
LPVOID lpSource,
SIZE_T uSourceSize
);
Parameters
FileTypeSet
[in] The file type set to be used for Normalization. See also File Type Sets.
NormalizeFlags
[in] Flags to be applied during the normalization process. DELTA_FLAG_RELOCS will disable the relocs transform portion of normalization. DELTA_FLAG_NONE is the only other flag currently supported for this parameter. See also DELTA_FLAG_TYPE flags.
NormalizeOptions
[in] Reserved. Pass a DELTA_INPUT structure with lpStart set to NULL and uSize set to 0.
lpSource
[in] Pointer to the source buffer.
uSourceSize
[in] Size of the source buffer in bytes.
Return Values
Returns TRUE on success or FALSE otherwise.
See also MSDelta Error Codes.
Requirements
| Header | Declared in msdelta.h |
| DLL | Requires msdelta.dll |
| Unicode | Not applicable |
See Also
- GetDeltaSignatureA/W
- GetDeltaSignatureB
DeltaFree
The DeltaFree function frees the specified memory block. You must call this function after the completion of any *B function that returns a DELTA_OUTPUT structure containing a pointer to an MSDelta-allocated memory buffer. Specifically, this function should be called after successful calls to CreateDeltaB and ApplyDeltaB.
Syntax
BOOL WINAPI DeltaFree(
LPVOID lpMemory
);
Parameters
lpMemory
[in] Memory block to be freed.
Return Values
Returns TRUE on success or FALSE otherwise.
See also MSDelta Error Codes.
Requirements
| Header | Declared in msdelta.h |
| DLL | Requires msdelta.dll |
| Unicode | Not applicable |
See Also
- CreateDeltaB
- ApplyDeltaB