EN
Este contenido no se encuentra disponible en su idioma, pero aquí tiene la versión en inglés.

# Delta Compression Application Programming Interfaces

Microsoft Corporation

January 2006

Note: This is pre-release documentation and subject to change in future releases.

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:
Microsoft® Windows XP
®    Windows 2000
®    Windows Server 2003
®    Windows Vista

®
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:
Microsoft Windows Vista

## Developer Audience

This documentation is intended for software developers who want to programmatically create deltas (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.

## 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.

## 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.

### 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'.

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'.

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:

1. Determines the file type of the source.
2. Preprocesses the source and creates source preprocessing information specific to the determined file type, the target, and optional parameters. (Transform Procedure)
3. Creates the compression stream for the target.
4. 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:

1. 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)
2. 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.

Figure 3. Delta compression using symbol files in PatchAPI

## PatchAPI

Microsoft Corporation

January 2006

Note: This is pre-release documentation and subject to change in future releases.

Microsoft Corporation

January 2006

### 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 Installer SDK    Windows Vista

®

### 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, and Windows Vista. 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 Windows Installer SDK.
• patchapi.h: Header file that defines the API functions, structures, and constants. This header is part of the current version of Windows Installer SDK.

1. Go to the Windows Server 2003 SP1 Platform SDK Installer page.
3. When prompted, choose Run.

By default, 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

### 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.

### 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).

### Progress Callback

The following functions provide progress reporting through a caller-specified progress callback function:

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.

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_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:

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.

### 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:

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.

### Flags

The API supports different flags to specify options. They can be grouped as follows:

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

January 2006

Note: This is pre-release documentation and subject to change in future releases.

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).

ApplyPatch Functions

Functions Description
ApplyPatchToFileA Apply deltas without progress reporting.
ApplyPatchToFileExA Apply deltas with progress reporting (see Progress Callbacks).
TestApplyPatchToFileA Verify that a delta or delta header matches a source file that it is being applied to.

These functions do not actually apply deltas.

Functions Description

Get Signatures

Functions Description
GetFilePatchSignatureA 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.

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.

Requirements

Header Declared in patchapi.h Requires mspatchc.dll Implemented as CreatePatchFileW (Unicode) and CreatePatchFileA (ANSI)

### 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.
Requirements

Header Declared in patchapi.h Requires mspatchc.dll Not applicable

### 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.

Requirements

Header Declared in patchapi.h Requires mspatchc.dll Implemented as CreatePatchFileExW (Unicode) and CreatePatchFileExA (ANSI)

### 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.
Requirements

Header Declared in patchapi.h Requires mspatchc.dll Not applicable

### 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.

#### Requirements

Header Declared in patchapi.h Requires mspatcha.dll Implemented as ApplyPatchToFileW (Unicode) and ApplyPatchToFileA (ANSI)

### 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.

OldFileHandle

Optional.
Handle to the source file to which the delta is to be applied.

NewFileHandle

Handle to the target file that is to be created.

ApplyOptionFlags

ApplyPatch Flags.

#### Return Values

Returns TRUE on success or FALSE otherwise.

Requirements

Header Declared in patchapi.h Requires mspatcha.dll Not applicable

### 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.

#### Requirements

Header Declared in patchapi.h Requires mspatcha.dll Not applicable

### 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.

Requirements

Header Declared in patchapi.h Requires mspatcha.dll Implemented as ApplyPatchToFileExW (Unicode) and ApplyPatchToFileExA (ANSI)

### 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.

OldFileHandle

Optional.
Handle to the source file to which the delta is applied.

NewFileHandle

Handle to the target file that is 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.

Requirements

Header Declared in patchapi.h Requires mspatcha.dll Not applicable

### 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.

#### Requirements

Header Declared in patchapi.h Requires mspatcha.dll Implemented as TestApplyPatchToFileW (Unicode) and TestApplyPatchToFileA (ANSI)

### 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.

Requirements

Header Declared in patchapi.h Requires mspatcha.dll Not applicable

### 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.

Requirements

Header Declared in patchapi.h Requires mspatcha.dll Not applicable

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,
);

LPCWSTR  PatchFileName,
);



#### Parameters

PatchFileName

The name of the delta containing the header.

The name of the header file that is to be created.

#### Return Values

Returns TRUE on success or FALSE otherwise.

Requirements

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,
);



#### Parameters

PatchFileName

Handle to the delta containing the header.

Handle to the header file that is to be created.

#### Return Values

Returns TRUE on success or FALSE otherwise.

Requirements

Header Declared in patchapi.h Requires mspatchc.dll Not applicable

### 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 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.

Requirements

Header Declared in patchapi.h Requires mspatcha.dll or mspatchc.dll Implemented as GetFilePatchSignatureW (Unicode) and GetFilePatchSignatureA (ANSI).

### 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 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.

Requirements

Header Declared in patchapi.h Requires mspatcha.dll or mspatchc.dll Not applicable

### 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.

Requirements

Header Declared in patchapi.h Requires mspatcha.dll or mspatchc.dll Not applicable

## MSDelta

Microsoft Corporation

January 2006

Note: This is pre-release documentation and subject to change in future releases.

### 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 Microsoft Windows Vista and may also be used in other scenarios.

#### Applies to:

Microsoft® Windows Vista

®

### 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. 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

# What's New in MSDelta

Microsoft Corporation

January 2006

Note: This is pre-release documentation and subject to change in future releases.

MSDelta is the next generation of the Delta Compression technology previously released as PatchAPI (which will continue to be supported). While PatchAPI will continue to be supported in Windows Vista, MSDelta adds value in the following ways:

• While PatchAPI offered specialized handling only for i386 executable files, MSDelta includes special handling for ia64, amd64 and MSIL formats as well. This allows for much smaller deltas than would be possible without optimization for these file types.
• 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.

### File Type Sets

Note: This is pre-release documentation and subject to change in future releases.

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 and DELTA_FILE_TYPE_SET_EXECUTABLES.

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 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 Raw file type.
DELTA_FILE_TYPE_I386 File type for Intel x386 (I386) Portable Executable files.
DELTA_FILE_TYPE_IA64 File type for Intel Itanium (IA64) Portable Executable files.
DELTA_FILE_TYPE_AMD64 File type for AMD 64-bit (AMD64) Portable Executable files.
DELTA_FILE_TYPE_SET_RAW_ONLY Same as DELTA_FILE_TYPE_RAW.
DELTA_FILE_TYPE_SET_EXECUTABLES File type set that includes I386, IA64 and AMD64 Portable Executable (PE) file types.

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
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
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 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_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

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;



#### Members

FileTypeSet

The file type set used during Create, which will also be used during the Apply process.

FileType

The specific file type of the source file.

Flags

The flags used during Create, which will also be used during the Apply process.

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

Note: This is pre-release documentation and subject to change in future releases.

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_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.

### MSDelta Error Codes

Note: This is pre-release documentation and subject to change in future releases.

When an MSDelta function returns FALSE, you can call GetLastError to get the corresponding Win32 system error code.

## MSDelta Reference

Microsoft Corporation

January 2006

Note: This is pre-release documentation and subject to change in future releases.

The tables below list the MSDelta functions grouped by the following categories.

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.

• 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

Note: This is pre-release documentation and subject to change in future releases.

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.

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.

Requirements

Header Declared in msdelta.h Requires msdelta.dll Implemented as CreateDeltaW createdeltaaw (Unicode) and CreateDeltaA createdeltaaw (ANSI)

### CreateDeltaB

Note: This is pre-release documentation and subject to change in future releases.

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.

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.

Requirements

Header Declared in msdelta.h Requires msdelta.dll Not applicable

### ApplyDeltaA/W

Note: This is pre-release documentation and subject to change in future releases.

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.

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.

Requirements

Header Declared in msdelta.h Requires msdelta.dll Requires mspatcha.dll when applying a delta created using PatchAPI. Implemented as ApplyDeltaW (Unicode) and ApplyDeltaA (ANSI)

## ApplyDeltaB

Note: This is pre-release documentation and subject to change in future releases.

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.

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.

Requirements

Header Declared in msdelta.h Requires msdelta.dll Requires mspatcha.dll when applying a delta created using PatchAPI. Not applicable

## ApplyDeltaProvidedB

Note: This is pre-release documentation and subject to change in future releases.

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.

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.

#### Requirements

Header Declared in msdelta.h Requires msdelta.dll Requires mspatcha.dll when applying a delta created using PatchAPI. Not applicable

• ApplyDeltaA/W

### GetDeltaInfoA/W

Note: This is pre-release documentation and subject to change in future releases.

The GetDeltaInfoA and GetDeltaInfoW functions retrieve information about a specified delta.

Syntax

BOOL  WINAPI  GetDeltaInfoA(
LPCSTR               lpDeltaName,
);

BOOL  WINAPI  GetDeltaInfoW(
LPWCSTR              lpDeltaName,
);



#### Parameters

lpDeltaName

[in] The name of the delta file from which to extract the information.

[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.

#### Requirements

Header Declared in msdelta.h Requires msdelta.dll Implemented as GetDeltaInfoW (Unicode) and GetDeltaInfoA (ANSI)

### GetDeltaInfoB

Note: This is pre-release documentation and subject to change in future releases.

The GetDeltaInfoB function retrieves information about a specified delta.

Syntax

BOOL  WINAPI  GetDeltaInfoB(
DELTA_INPUT          Delta,
);



#### Parameters

Delta

[in] DELTA_INPUT structure containing a pointer to the buffer containing the delta.

[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.

Requirements

Header Declared in msdelta.h Requires msdelta.dll Requires mspatcha.dll when provided a delta created using PatchAPI. Not applicable

### GetDeltaSignatureA/W

Note: This is pre-release documentation and subject to change in future releases.

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.

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.

Requirements

Header Declared in msdelta.h Requires msdelta.dll Implemented as GetDeltaSignatureW (Unicode) and GetDeltaSignatureA (ANSI).

### GetDeltaSignatureB

Note: This is pre-release documentation and subject to change in future releases.

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.

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.

Requirements

Header Declared in msdelta.h Requires msdelta.dll Not applicable

### DeltaNormalizeProvidedB

Note: This is pre-release documentation and subject to change in future releases.

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.

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.

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.

Requirements

Header Declared in msdelta.h Requires msdelta.dll Not applicable

### DeltaFree

Note: This is pre-release documentation and subject to change in future releases.

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.