Decompress

Simple API

The simplest decompression function.

Note

Rich error information only works with decompression operations that take a ZL_DCtx*, so if the operation fails this function won't provide details.

ZL_Report ZL_decompress(void* dst, size_t dstCapacity, const void* src,
                        size_t srcSize);

Decompresses a frame hosting a single serialized output.

Parameters:

• dst –

  Destination buffer for decompressed data

• dstCapacity –

  Size of destination buffer in bytes

• src –

  Source compressed data

• srcSize –

  Size of source data in bytes

Returns:

Either an error (check with ZL_isError()) or decompressed size on success

Querying Compressed Frames

ZL_Report ZL_getCompressedSize(const void* compressed, size_t testedSize);

Gets the size of the compressed frame. This method could be useful when the compressed frame only represents a first portion of a larger buffer.

Parameters:

• compressed –

  Pointer to compressed data. Must point at the start of a compressed frame.

• testedSize –

  Size of data compressed points to. To be useful, at a minimum, this size must be:

  • frame header + chunk header for version < ZL_CHUNK_VERSION_MIN.

  • = compressedSize for frames of versions >= ZL_CHUNK_VERSION_MIN.

Returns:

Compressed frame size in bytes, or error code

Note

Huge content sizes (> 4 GB) can't be represented on 32-bit systems

ZL_FrameInfo* ZL_FrameInfo_create(const void* compressed, size_t cSize);

Creates a frame information object from compressed data.

Parameters:

• compressed –

  Pointer to compressed data

• cSize –

  Size of compressed data

Returns:

Pointer to frame info object, or NULL on error

void ZL_FrameInfo_free(ZL_FrameInfo* fi);

Frees a frame information object.

Parameters:

• fi –

  Frame information object to free

ZL_Report ZL_FrameInfo_getFormatVersion(const ZL_FrameInfo* fi);

Gets the format version of the frame.

Parameters:

• fi –

  Frame information object

Returns:

The version number, or error if unsupported or invalid

ZL_Report ZL_FrameInfo_getNumOutputs(const ZL_FrameInfo* fi);

Gets the number of regenerated outputs on decompression.

Parameters:

• fi –

  Frame information object

Returns:

The number of outputs on decompression

ZL_Report ZL_FrameInfo_getOutputType(const ZL_FrameInfo* fi, int outputID);

Gets the output type for a specific output ID.

Parameters:

• fi –

  Frame information object

• outputID –

  Output ID (starts at 0, single output has ID 0)

Returns:

Output type, or error code

ZL_Report ZL_FrameInfo_getDecompressedSize(const ZL_FrameInfo* fi,
                                           int outputID);

Gets the decompressed size of a specific output.

Parameters:

• fi –

  Frame information object

• outputID –

  Output ID (starts at 0)

Returns:

Size of specified output in bytes, or error code

Helper Functions

These functions are wrappers around the ZL_FrameInfo functions that provide simple APIs for common cases.

ZL_Report ZL_getDecompressedSize(const void* compressed, size_t cSize);

Gets the decompressed size of content from a single-output frame.

Useful to determine the size of buffer to allocate.

Parameters:

• compressed –

  Pointer to compressed data

• cSize –

  Size of compressed frame or at a minimum the size of the complete frame header

Returns:

Decompressed size in bytes, or error code

Note

Huge content sizes (> 4 GB) can't be represented on 32-bit systems

Note

For String type,

Returns:

size of all strings concatenated

ZL_Report ZL_getNumOutputs(const void* compressed, size_t cSize);

Gets the number of outputs stored in a compressed frame.

Doesn't need the whole frame, just enough to read the requested information.

Parameters:

• compressed –

  Pointer to compressed data

• cSize –

  Size of compressed data

Returns:

Number of outputs, or error on failure (invalid frame, size too small, etc.)

ZL_Report ZL_getOutputType(ZL_Type* stPtr, const void* compressed,
                           size_t cSize);

Gets the output type for single-output frames.

Only works for single-output frames. Provides the type of the single output.

Parameters:

• stPtr –

  Pointer to store the output type

• compressed –

  Pointer to compressed data

• cSize –

  Size of compressed data

Returns:

Error code or success

Note

Only works for single-output frames

Lifetime Management

ZL_DCtx* ZL_DCtx_create(void);

Creates a new decompression context.

Returns:

Pointer to new context, or NULL on error

void ZL_DCtx_free(ZL_DCtx* dctx);

Frees a decompression context.

Parameters:

• dctx –

  Decompression context to free

Parameterization

ZL_Report ZL_DCtx_setParameter(ZL_DCtx* dctx, ZL_DParam gdparam, int value);

Sets global parameters via the decompression context.

Parameters:

• dctx –

  Decompression context

• gdparam –

  Parameter to set

• value –

  Value to set for the parameter

Returns:

Error code or success

Note

By default, parameters are reset at end of decompression session. To preserve them across sessions, set stickyParameters=1

int ZL_DCtx_getParameter(const ZL_DCtx* dctx, ZL_DParam gdparam);

Reads a parameter's configured value in the decompression context.

Parameters:

• dctx –

  Decompression context

• gdparam –

  Parameter to query

Returns:

The value set for the given parameter, or 0 if unset/nonexistent

ZL_Report ZL_DCtx_resetParameters(ZL_DCtx* dctx);

Resets parameters selection from a blank slate.

Useful when unsure if ZL_DParam_stickyParameters is set to 1.

Parameters:

• dctx –

  Decompression context

Returns:

Error code or success

Errors and Warnings

char const* ZL_DCtx_getErrorContextString(ZL_DCtx const* dctx,
                                          ZL_Report report);

Gets a verbose error string containing context about the error.

Useful for debugging and submitting bug reports to OpenZL developers.

Parameters:

• dctx –

  Decompression context

• report –

  Error report to get context for

Returns:

Error context string

Note

String is stored within the dctx and is only valid for the lifetime of the dctx

char const* ZL_DCtx_getErrorContextString_fromError(ZL_DCtx const* dctx,
                                                    ZL_Error error);

Gets error context string from error code.

Parameters:

• dctx –

  Decompression context

• error –

  Error code to get context for

Returns:

Error context string

Note

String is stored within the dctx and is only valid for the lifetime of the dctx

ZL_Error_Array ZL_DCtx_getWarnings(ZL_DCtx const* dctx);

Gets the array of warnings from the previous operation.

Parameters:

• dctx –

  Decompression context

Returns:

Array of warnings encountered during the previous operation

Note

Array and errors' lifetimes are valid until the next non-const call on the DCtx

Serial Decompression

ZL_Report ZL_DCtx_decompress(ZL_DCtx* dctx, void* dst, size_t dstCapacity,
                             const void* compressed, size_t cSize);

Decompresses data with explicit state management.

Same as ZL_decompress(), but with explicit state management. The state can be used to store advanced parameters.

Parameters:

• dctx –

  Decompression context

• dst –

  Destination buffer for decompressed data

• dstCapacity –

  Size of destination buffer in bytes

• compressed –

  Source compressed data

• cSize –

  Size of compressed data in bytes

Returns:

Error code or decompressed size on success

Typed Decompression

ZL_Report ZL_DCtx_decompressTBuffer(ZL_DCtx* dctx, ZL_TypedBuffer* output,
                                    const void* compressed, size_t cSize);

Decompresses a frame with a single typed output into a TypedBuffer.

This prototype works for frames with a single typed output only. Data will be decompressed into the output buffer.

Parameters:

• dctx –

  Decompression context

• output –

  TypedBuffer object (must be created first)

• compressed –

  Pointer to compressed data

• cSize –

  Size of compressed data in bytes

Returns:

Error code or size in bytes of the main buffer inside output

Note

Output is filled on success, but undefined on error, and can only be free() in this case.

Note

ZL_TypedBuffer object is required to decompress String type

ZL_Report ZL_DCtx_decompressMultiTBuffer(ZL_DCtx* dctx, ZL_TypedBuffer* outputs,
                                         size_t nbOutputs,
                                         const void* compressed, size_t cSize);

Decompresses a frame into multiple TypedBuffers.

Parameters:

• dctx –

  Decompression context

• outputs –

  Array of ZL_TypedBuffer* objects (must be created using ZL_TypedBuffer_create or pre-allocated creation methods)

• nbOutputs –

  Exact number of outputs expected from the frame (can be obtained from ZL_FrameInfo_getNumOutputs())

• compressed –

  Pointer to compressed data

• cSize –

  Size of compressed data in bytes

Returns:

Error code or number of decompressed TypedBuffers

Note

Requires exact number of outputs (not permissive)

Note

outputs are filled on success, but undefined on error

Note

TypedBuffer lifetimes are controlled by the caller

ZL_TypedBuffer

Note

ZL_TypedBuffer will be replaced with ZL_Input soon. So expect these function names to change.

ZL_TypedBuffer* ZL_TypedBuffer_create(void);

Creates an empty typed buffer object.

On creation, the TypedBuffer object is empty. By default, when provided as an empty shell, it will automatically allocate and fill its own buffer during invocation of ZL_DCtx_decompressTBuffer(). A TypedBuffer object is not reusable and must be freed after usage. Releasing the object also releases its owned buffers.

Returns:

Pointer to new typed buffer, or NULL on error

ZL_TypedBuffer* ZL_TypedBuffer_createWrapSerial(void* buffer,
                                                size_t bufferCapacity);

Creates a pre-allocated typed buffer for serial data.

The object will use the referenced buffer, and not allocate its own one. It will be filled during invocation of ZL_DCtx_decompressTBuffer(). Releasing the ZL_TypedBuffer object will not release the referenced buffer.

Parameters:

• buffer –

  buffer to write into

• bufferCapacity –

  maximum size to write into buffer

Returns:

Pointer to wrapped typed buffer, or NULL on error

ZL_TypedBuffer* ZL_TypedBuffer_createWrapStruct(void* structBuffer,
                                                size_t structWidth,
                                                size_t numStructs);

Creates a pre-allocated typed buffer for struct data.

Parameters:

• structBuffer –

  buffer to write struct into. Its size must be at least structWidth * structCapacity

• structWidth –

  Width of each struct in bytes

• structCapacity –

  Maximum number of struct that can be written into structBuffer

Returns:

Pointer to wrapped typed buffer, or NULL on error

ZL_TypedBuffer* ZL_TypedBuffer_createWrapNumeric(void* numArray,
                                                 size_t numWidth,
                                                 size_t numCapacity);

Creates a pre-allocated typed buffer for numeric data.

Parameters:

• numArray –

  buffer to write the array of numeric values into The array size must be >= numWidth * numCapacity. It must also be correctly aligned for the numeric width requested.

• numWidth –

  Width of numeric values in bytes

• numCapacity –

  Maximum number of numeric value that can be written into numArray

Returns:

Pointer to wrapped typed buffer, or NULL on error

void ZL_TypedBuffer_free(ZL_TypedBuffer* tbuffer);

Frees a typed buffer object.

Parameters:

• tbuffer –

  Typed buffer to free

ZL_Type ZL_TypedBuffer_type(const ZL_TypedBuffer* tbuffer);

Gets the type of the typed buffer.

Once decompression is completed, the ZL_TypedBuffer object can be queried. Here are its accessors:

Parameters:

• tbuffer –

  Typed buffer object

Returns:

Type of the buffer

const void* ZL_TypedBuffer_rPtr(const ZL_TypedBuffer* tbuffer);

Gets direct access to the internal buffer for reading operation.

Parameters:

• tbuffer –

  Typed buffer object

Returns:

Pointer to the beginning of buffer (for String type, points at the beginning of the first string).

Warning

Users must pay attention to buffer boundaries

Note

Buffer size is provided by ZL_TypedBuffer_byteSize()

size_t ZL_TypedBuffer_byteSize(const ZL_TypedBuffer* tbuffer);

Gets the number of bytes written into the internal buffer.

Parameters:

• tbuffer –

  Typed buffer object

Returns:

Number of bytes in the internal buffer.

Note

Generally equals eltWidth * nbElts, but for String type equals sum(stringLens)

Note

ZL_DCtx_decompressTBuffer() returns the same value

size_t ZL_TypedBuffer_numElts(const ZL_TypedBuffer* tbuffer);

Gets the number of elements in the typed buffer.

Parameters:

• tbuffer –

  Typed buffer object

Returns:

Number of elements in the buffer

Note

for Serial type, this is the number of bytes.

size_t ZL_TypedBuffer_eltWidth(const ZL_TypedBuffer* tbuffer);

Gets the size of each element for fixed-size types.

Parameters:

• tbuffer –

  Typed buffer object

Returns:

Size of each element in bytes, or 0 for String type

Note

Not valid for String type (returns 0)

const uint32_t* ZL_TypedBuffer_rStringLens(const ZL_TypedBuffer* tbuffer);

Gets pointer to the array of string lengths.

Parameters:

• tbuffer –

  Typed buffer object

Returns:

Pointer to beginning of string lengths array, or NULL if incorrect type

Note

Only valid for String type

Note

Array size equals ZL_TypedBuffer_numElts()