Decompress function (compressapi.h)

Takes a block of compressed information and decompresses it.

Syntax

BOOL Decompress(
  [in]  DECOMPRESSOR_HANDLE DecompressorHandle,
  [in]  LPCVOID             CompressedData,
  [in]  SIZE_T              CompressedDataSize,
  [out] PVOID               UncompressedBuffer,
  [in]  SIZE_T              UncompressedBufferSize,
  [out] PSIZE_T             UncompressedDataSize
);

Parameters

[in] DecompressorHandle

Handle to a decompressor returned by CreateDecompressor.

[in] CompressedData

Contains the block of information that is to be decompressed. The size in bytes of the compressed block is given by CompressedDataSize.

[in] CompressedDataSize

The size in bytes of the compressed information.

[out] UncompressedBuffer

The buffer that receives the uncompressed information. The size in bytes of the buffer is given by UncompressedBufferSize.

[in] UncompressedBufferSize

Size in bytes of the buffer that receives the uncompressed information.

[out] UncompressedDataSize

Actual size in bytes of the uncompressed information received.

Return value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

If the block of compressed data pointed to by CompressedData is corrupted, the function can fail and the error from GetLastError can be ERROR_BAD_COMPRESSION_BUFFER. It is also possible that the function will produce a block of uncompressed data that does not match the original data.

It is recommended that compressors and decompressors not use the COMPRESS_RAW flag. If the compressor is created with the COMPRESS_RAW flag, the decompressor must also be created with the COMPRESS_RAW flag.

If the compressor and decompressor are created using the COMPRESS_RAW flag, the value of UncompressedBufferSize must be exactly equal to the original size of the uncompressed data and not just the size of the output buffer. This means you should save the exact original size of the uncompressed data, as well as the compressed data and compressed size, when using the COMPRESS_RAW flag. If UncompressedBufferSize does not equal the original size of the uncompressed data, the uncompressed data will not match the original data. In this case, the function can return success or it can return ERROR_BAD_COMPRESSION_BUFFER.

If the COMPRESS_RAW flag is not used, UncompressedBufferSize is not required to be exactly equal to the original size of the uncompressed data. In this case, UncompressedDataSize returns the original size of the uncompressed data. If UncompressedBufferSize is smaller than the original data size, the function will fail and set UncompressedDataSize to the size of the original data and the error from GetLastError is ERROR_INSUFFICIENT_BUFFER.

To determine how large the UncompressedBuffer needs to be, call the function with UncompressedBufferSize set to zero. In this case, the function will fail and set UncompressedDataSize to the size of the original data and the error from GetLastError is ERROR_INSUFFICIENT_BUFFER. Note that the original size returned by the function is extracted from the buffer itself and should be treated as untrusted and tested against reasonable limits.

If the function is called with the CompressedDataSize parameter set to zero, the function fails and the error from GetLastError is ERROR_INSUFFICIENT_BUFFER. When it fails the function returns with UncompressedDataSize set to a value that you can use to avoid allocating too large a buffer for the compressed data. You must know the maximum possible size of the original data to use this method.

If you set CompressedDataSize to zero, and set UncompressedBufferSize to the maximum possible size of the original uncompressed data, the Decompress function will fail as described and the value of UncompressedDataSize will be set to the maximum size for the compressed data buffer.

If the compression algorithm fails for some internal reason, the error from GetLastError can be ERROR_FUNCTION_FAILED. If the system cannot locate the compression algorithm handle, the error can be ERROR_INVALID_HANDLE. If the output buffer is too small to hold the uncompressed data, the error can be ERROR_INSUFFICIENT_BUFFER.

Requirements

Requirement Value
Minimum supported client Windows 8 [desktop apps | UWP apps]
Minimum supported server Windows Server 2012 [desktop apps | UWP apps]
Target Platform Windows
Header compressapi.h
Library Cabinet.lib
DLL Cabinet.dll

See also

Compression API Functions