RtlDecompressBufferEx2 function (ntifs.h)

Article
09/27/2023

The RtlDecompressBufferEx2 function decompresses an entire compressed buffer, using multiple processors where possible. Multiple processor support is only implemented for kernel mode callers.

Syntax

NT_RTL_COMPRESS_API NTSTATUS RtlDecompressBufferEx2(
  [in]           USHORT CompressionFormat,
  [out]          PUCHAR UncompressedBuffer,
  [in]           ULONG  UncompressedBufferSize,
  [in]           PUCHAR CompressedBuffer,
  [in]           ULONG  CompressedBufferSize,
  [in]           ULONG  UncompressedChunkSize,
  [out]          PULONG FinalUncompressedSize,
  [in, optional] PVOID  WorkSpace
);

Parameters

[in] CompressionFormat

A bitmask that specifies the compression format of the compressed buffer. This parameter must be set to COMPRESSION_FORMAT_LZNT1. The meaning of this and other related compression format values are as follows.

Value	Meaning
COMPRESSION_FORMAT_NONE	Not supported by this function.
COMPRESSION_FORMAT_DEFAULT	Not supported by this function.
COMPRESSION_FORMAT_LZNT1	The function will perform LZ compression.
COMPRESSION_FORMAT_XPRESS	The function will perform Xpress compression.
COMPRESSION_FORMAT_XPRESS_HUFF	The function will perform Xpress Huffman decompression.

[out] UncompressedBuffer

A pointer to a caller-allocated buffer (allocated from a paged or non-paged pool) that receives the decompressed data from CompressedBuffer. This parameter is required and cannot be NULL.

[in] UncompressedBufferSize

The size, in bytes, of the UncompressedBuffer buffer.

[in] CompressedBuffer

A pointer to the buffer that contains the data to decompress. This parameter is required and cannot be NULL.

[in] CompressedBufferSize

The size, in bytes, of the CompressedBuffer buffer.

[in] UncompressedChunkSize

The size, in bytes, of each chunk within the compression buffer. Valid values are 512, 1024, 2048 and 4096.

[out] FinalUncompressedSize

A pointer to a caller-allocated variable that receives the size, in bytes, of the decompressed data stored in UncompressedBuffer. This parameter is required and cannot be NULL.

[in, optional] WorkSpace

A pointer to a caller-allocated work space buffer used by the RtlDecompressBufferEx2 function during decompression. Use the RtlGetCompressionWorkSpaceSize function to determine the correct work space buffer size.

Return value

RtlDecompressBufferEx2 returns an appropriate error status value, such as one of the following.

Return code	Description
STATUS_SUCCESS	The CompressedBuffer buffer was successfully decompressed.
STATUS_INVALID_PARAMETER	An invalid compression format was specified through the CompressionFormat parameter. If CompressionFormat is either COMPRESSION_FORMAT_NONE or COMPRESSION_FORMAT_DEFAULT (but not both), this value is returned.
STATUS_UNSUPPORTED_COMPRESSION	An invalid compression format was specified through the CompressionFormat parameter. If CompressionFormat is not one of the following, STATUS_UNSUPPORTED_COMPRESSION is returned: COMPRESSION_FORMAT_LZNT1, COMPRESSION_FORMAT_XPRESS, COMPRESSION_FORMAT_XPRESS_HUFF, COMPRESSION_FORMAT_NONE, COMPRESSION_FORMAT_DEFAULT
STATUS_BAD_COMPRESSION_BUFFER	UncompressedBuffer is not large enough to contain the uncompressed data.

Remarks

The RtlDecompressBufferEx2 function takes as input an entire compressed buffer and produces its decompressed equivalent provided that the uncompressed data fits within the specified destination buffer.

To decompress only a portion of a compressed buffer (that is, a "fragment" of the buffer), use the RtlDecompressFragment function.

To compress an uncompressed buffer, use the RtlCompressBuffer function.

Requirements

Requirement	Value
Minimum supported client	Windows 10
Target Platform	Universal
Header	ntifs.h (include Fltkernel.h, Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL