Windows Driver Kit: Installable File System Drivers
RtlCompressBuffer
The RtlCompressBuffer function compresses a buffer and can be used by a file system driver to facilitate the implementation of file compression.
NTSTATUS
RtlCompressBuffer (
__in USHORT CompressionFormatAndEngine,
__in PUCHAR UncompressedBuffer,
__in ULONG UncompressedBufferSize,
__out PUCHAR CompressedBuffer,
__in ULONG CompressedBufferSize,
__in ULONG UncompressedChunkSize,
__out PULONG FinalCompressedSize,
__in PVOID WorkSpace
);
Parameters
- CompressionFormatAndEngine
- A 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:
| Value | Meaning |
|---|
| 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 | The UncompressedBuffer buffer 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 | The UncompressedBuffer buffer 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. |
- UncompressedBuffer
- A pointer to a caller-allocated buffer (allocated from paged or non-paged pool) containing the data to be compressed. This parameter is required and cannot be NULL.
- UncompressedBufferSize
- Size, in bytes, of the UncompressedBuffer buffer.
- CompressedBuffer
- A pointer to a caller-allocated buffer (allocated from paged or non-paged pool) receiving the compressed data. This parameter is required and cannot be NULL.
- CompressedBufferSize
- Size, in bytes, of the CompressedBuffer buffer.
- UncompressedChunkSize
- The chunk size to use when compressing the UncompressedBuffer buffer. This parameter must be one of the following values: 512, 1024, 2048, or 4096. The operating system uses 4096, and the recommended value for this parameter is also 4096.
- FinalCompressedSize
- A pointer to a caller-allocated variable which receives the size, in bytes, of the compressed data stored in CompressedBuffer. This parameter is required and cannot be NULL.
- WorkSpace
- A pointer to a caller-allocated work space buffer used by the RtlCompressBuffer function during compression. Use the RtlGetCompressionWorkSpaceSize function to determine the correct work space buffer size.
Return Value
RtlCompressBuffer returns an appropriate error status value, such as one of the following:
- STATUS_SUCCESS
- The UncompressedBuffer buffer was successfully compressed.
- STATUS_BUFFER_ALL_ZEROS
- The UncompressedBuffer buffer was successfully compressed but this buffer contains only zeros.
- STATUS_INVALID_PARAMETER
- STATUS_UNSUPPORTED_COMPRESSION
- 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.
- STATUS_BUFFER_TOO_SMALL
- The compressed buffer is too small to hold the compressed data. That is, FinalCompressedSize is greater than CompressedBufferSize.
Comments
The RtlCompressBuffer function takes as input an uncompressed buffer and produces its compressed equivalent provided that the compressed data fits within the specified destination buffer.
To determine the correct buffer size for the WorkSpace parameter, use the RtlGetCompressionWorkSpaceSize function.
To decompress a compressed buffer, use the RtlDecompressBuffer function.
To extract an uncompressed fragment from a compressed buffer, use the RtlDecompressFragment function.
Requirements
Versions: Available in Microsoft Windows XP and later versions of all Windows operating systems.
IRQL: <= APC_LEVEL
Headers: Declared in Ntifs.h. Include Fltkernel.h or Ntifs.h.
Library: Contained in Ntoskrnl.lib.
See Also
FILE_COMPRESSION_INFORMATION, RtlDecompressBuffer, RtlDecompressFragment, RtlGetCompressionWorkSpaceSize