RtlGetCompressionWorkSpaceSize function

The RtlGetCompressionWorkSpaceSize function is used to determine the correct size of the WorkSpace buffer for the RtlCompressBuffer and RtlDecompressFragment functions.

Syntax


NTSTATUS RtlGetCompressionWorkSpaceSize(
  _In_  USHORT CompressionFormatAndEngine,
  _Out_ PULONG CompressBufferWorkSpaceSize,
  _Out_ PULONG CompressFragmentWorkSpaceSize
);

Parameters

CompressionFormatAndEngine [in]

Bitmask specifying the compression format and engine type. This parameter must be set to one of the following bitwise OR combinations:

  • COMPRESSION_FORMAT_LZNT1 | COMPRESSION_ENGINE_STANDARD

  • COMPRESSION_FORMAT_LZNT1 | COMPRESSION_ENGINE_MAXIMUM

The meanings of these, and other related values, are as follows:

ValueMeaning

COMPRESSION_FORMAT_NONE

Not supported by this function.

COMPRESSION_FORMAT_DEFAULT

Not supported by this function.

COMPRESSION_FORMAT_LZNT1

Specifies that compression should be performed. This value is required.

COMPRESSION_ENGINE_STANDARD

Data is compressed using an algorithm which provides a balance between data compression and performance. This value cannot be used with COMPRESSION_ENGINE_MAXIMUM.

COMPRESSION_ENGINE_MAXIMUM

Data is compressed using an algorithm which provides maximum data compression but with relatively slower performance. This value cannot be used with COMPRESSION_ENGINE_STANDARD.

COMPRESSION_ENGINE_HIBER

Not supported by this function.

 

CompressBufferWorkSpaceSize [out]

A pointer to a caller-allocated buffer receiving the size, in bytes, required to compress a buffer. This value is used to determine the correct size of RtlCompressBuffer's WorkSpace buffer.

CompressFragmentWorkSpaceSize [out]

A pointer to a caller-allocated buffer receiving the size, in bytes, required to decompress a compressed buffer to a fragment. This value is used to determine the correct size of RtlDecompressFragment's WorkSpace buffer. Note that the RtlCompressFragment function does not currently exist.

Return value

RtlGetCompressionWorkSpaceSizereturns an appropriate error status, such as one of the following:

Return codeDescription
STATUS_SUCCESS

The required buffer sizes, in bytes, were successfully returned.

STATUS_INVALID_PARAMETER

An invalid compression format was specified via the CompressionFormatAndEngine parameter. If CompressionFormatAndEngine 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 via the CompressionFormatAndEngine parameter. If CompressionFormatAndEngine is not one of the following, STATUS_UNSUPPORTED_COMPRESSION is returned:

  • COMPRESSION_FORMAT_LZNT1
  • COMPRESSION_FORMAT_NONE (in this case, STATUS_INVALID_PARAMETER is returned)
  • COMPRESSION_FORMAT_DEFAULT (in this case, STATUS_INVALID_PARAMETER is returned)
STATUS_NOT_SUPPORTED

An invalid compression engine was specified via the CompressionFormatAndEngine parameter. If CompressionFormatAndEngine is not COMPRESSION_ENGINE_STANDARD or COMPRESSION_ENGINE_MAXIMUM (but not both), this value is returned.

 

Remarks

The RtlCompressBuffer and RtlDecompressFragmentfunctions require an appropriately sized work space buffer to compress and decompress successfully. To determine the correct work space buffer size, in bytes, call the RtlGetCompressionWorkSpaceSize function.

As an example, the WorkSpace parameter of the RtlCompressBuffer function must point to an adequately sized work space buffer. The CompressBufferWorkSpaceSize parameter of the RtlGetCompressionWorkSpaceSize provides this size.

To compress an uncompressed buffer, use the RtlCompressBuffer function.

To decompress a compressed buffer, use the RtlDecompressBuffer function.

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

Requirements

Target platform

Universal

Version

Available in Windows XP and all later versions of Windows operating systems.

Header

Ntifs.h (include Fltkernel.h or Ntifs.h)

Library

NtosKrnl.lib

DLL

NtosKrnl.exe

IRQL

<= APC_LEVEL

See also

FILE_COMPRESSION_INFORMATION
RtlCompressBuffer
RtlDecompressBuffer
RtlDecompressFragment

 

 

Send comments about this topic to Microsoft

Show: