lz4frame.h implements LZ4 frame specification (doc/lz4_Frame_format.md). lz4frame.h provides frame compression functions that take care of encoding standard metadata alongside LZ4-compressed blocks.
unsigned LZ4F_isError(LZ4F_errorCode_t code); /**< tells when a function result is an error code */
const char* LZ4F_getErrorName(LZ4F_errorCode_t code); /**< return error code string; for debugging */
typedef enum { LZ4F_default=0, LZ4F_max64KB=4, LZ4F_max256KB=5, LZ4F_max1MB=6, LZ4F_max4MB=7 LZ4F_OBSOLETE_ENUM(max64KB) LZ4F_OBSOLETE_ENUM(max256KB) LZ4F_OBSOLETE_ENUM(max1MB) LZ4F_OBSOLETE_ENUM(max4MB) } LZ4F_blockSizeID_t;
typedef enum { LZ4F_blockLinked=0, LZ4F_blockIndependent LZ4F_OBSOLETE_ENUM(blockLinked) LZ4F_OBSOLETE_ENUM(blockIndependent) } LZ4F_blockMode_t;
typedef enum { LZ4F_noContentChecksum=0, LZ4F_contentChecksumEnabled LZ4F_OBSOLETE_ENUM(noContentChecksum) LZ4F_OBSOLETE_ENUM(contentChecksumEnabled) } LZ4F_contentChecksum_t;
typedef enum { LZ4F_noBlockChecksum=0, LZ4F_blockChecksumEnabled } LZ4F_blockChecksum_t;
typedef enum { LZ4F_frame=0, LZ4F_skippableFrame LZ4F_OBSOLETE_ENUM(skippableFrame) } LZ4F_frameType_t;
typedef struct { LZ4F_blockSizeID_t blockSizeID; /* max64KB, max256KB, max1MB, max4MB; 0 == default */ LZ4F_blockMode_t blockMode; /* LZ4F_blockLinked, LZ4F_blockIndependent; 0 == default */ LZ4F_contentChecksum_t contentChecksumFlag; /* 1: frame terminated with 32-bit checksum of decompressed data; 0: disabled (default) */ LZ4F_frameType_t frameType; /* read-only field : LZ4F_frame or LZ4F_skippableFrame */ unsigned long long contentSize; /* Size of uncompressed content ; 0 == unknown */ unsigned dictID; /* Dictionary ID, sent by compressor to help decoder select correct dictionary; 0 == no dictID provided */ LZ4F_blockChecksum_t blockChecksumFlag; /* 1: each block followed by a checksum of block's compressed data; 0: disabled (default) */ } LZ4F_frameInfo_t;makes it possible to set or read frame parameters. Structure must be first init to 0, using memset() or LZ4F_INIT_FRAMEINFO, setting all parameters to default. It's then possible to update selectively some parameters
typedef struct { LZ4F_frameInfo_t frameInfo; int compressionLevel; /* 0: default (fast mode); values > LZ4HC_CLEVEL_MAX count as LZ4HC_CLEVEL_MAX; values < 0 trigger "fast acceleration" */ unsigned autoFlush; /* 1: always flush; reduces usage of internal buffers */ unsigned favorDecSpeed; /* 1: parser favors decompression speed vs compression ratio. Only works for high compression modes (>= LZ4HC_CLEVEL_OPT_MIN) */ /* v1.8.2+ */ unsigned reserved[3]; /* must be zero for forward compatibility */ } LZ4F_preferences_t;makes it possible to supply advanced compression instructions to streaming interface. Structure must be first init to 0, using memset() or LZ4F_INIT_PREFERENCES, setting all parameters to default. All reserved fields must be set to zero.
size_t LZ4F_compressFrameBound(size_t srcSize, const LZ4F_preferences_t* preferencesPtr);Returns the maximum possible compressed size with LZ4F_compressFrame() given srcSize and preferences. `preferencesPtr` is optional. It can be replaced by NULL, in which case, the function will assume default preferences. Note : this result is only usable with LZ4F_compressFrame(). It may also be used with LZ4F_compressUpdate() _if no flush() operation_ is performed.
size_t LZ4F_compressFrame(void* dstBuffer, size_t dstCapacity, const void* srcBuffer, size_t srcSize, const LZ4F_preferences_t* preferencesPtr);Compress an entire srcBuffer into a valid LZ4 frame. dstCapacity MUST be >= LZ4F_compressFrameBound(srcSize, preferencesPtr). The LZ4F_preferences_t structure is optional : you can provide NULL as argument. All preferences will be set to default. @return : number of bytes written into dstBuffer. or an error code if it fails (can be tested using LZ4F_isError())
typedef struct { unsigned stableSrc; /* 1 == src content will remain present on future calls to LZ4F_compress(); skip copying src content within tmp buffer */ unsigned reserved[3]; } LZ4F_compressOptions_t;
LZ4F_errorCode_t LZ4F_createCompressionContext(LZ4F_cctx** cctxPtr, unsigned version); LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx);The first thing to do is to create a compressionContext object, which will be used in all compression operations. This is achieved using LZ4F_createCompressionContext(), which takes as argument a version. The version provided MUST be LZ4F_VERSION. It is intended to track potential version mismatch, notably when using DLL. The function will provide a pointer to a fully allocated LZ4F_cctx object. If @return != zero, there was an error during context creation. Object can release its memory using LZ4F_freeCompressionContext();
size_t LZ4F_compressBegin(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_preferences_t* prefsPtr);will write the frame header into dstBuffer. dstCapacity must be >= LZ4F_HEADER_SIZE_MAX bytes. `prefsPtr` is optional : you can provide NULL as argument, all preferences will then be set to default. @return : number of bytes written into dstBuffer for the header or an error code (which can be tested using LZ4F_isError())
size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr);Provides minimum dstCapacity required to guarantee success of LZ4F_compressUpdate(), given a srcSize and preferences, for a worst case scenario. When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() instead. Note that the result is only valid for a single invocation of LZ4F_compressUpdate(). When invoking LZ4F_compressUpdate() multiple times, if the output buffer is gradually filled up instead of emptied and re-used from its start, one must check if there is enough remaining capacity before each invocation, using LZ4F_compressBound(). @return is always the same for a srcSize and prefsPtr. prefsPtr is optional : when NULL is provided, preferences will be set to cover worst case scenario. tech details : @return includes the possibility that internal buffer might already be filled by up to (blockSize-1) bytes. It also includes frame footer (ending + checksum), since it might be generated by LZ4F_compressEnd(). @return doesn't include frame header, as it was already generated by LZ4F_compressBegin().
size_t LZ4F_compressUpdate(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const void* srcBuffer, size_t srcSize, const LZ4F_compressOptions_t* cOptPtr);LZ4F_compressUpdate() can be called repetitively to compress as much data as necessary. Important rule: dstCapacity MUST be large enough to ensure operation success even in worst case situations. This value is provided by LZ4F_compressBound(). If this condition is not respected, LZ4F_compress() will fail (result is an errorCode). LZ4F_compressUpdate() doesn't guarantee error recovery. When an error occurs, compression context must be freed or resized. `cOptPtr` is optional : NULL can be provided, in which case all options are set to default. @return : number of bytes written into `dstBuffer` (it can be zero, meaning input data was just buffered). or an error code if it fails (which can be tested using LZ4F_isError())
size_t LZ4F_flush(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_compressOptions_t* cOptPtr);When data must be generated and sent immediately, without waiting for a block to be completely filled, it's possible to call LZ4_flush(). It will immediately compress any data buffered within cctx. `dstCapacity` must be large enough to ensure the operation will be successful. `cOptPtr` is optional : it's possible to provide NULL, all options will be set to default. @return : nb of bytes written into dstBuffer (can be zero, when there is no data stored within cctx) or an error code if it fails (which can be tested using LZ4F_isError()) Note : LZ4F_flush() is guaranteed to be successful when dstCapacity >= LZ4F_compressBound(0, prefsPtr).
size_t LZ4F_compressEnd(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_compressOptions_t* cOptPtr);To properly finish an LZ4 frame, invoke LZ4F_compressEnd(). It will flush whatever data remained within `cctx` (like LZ4_flush()) and properly finalize the frame, with an endMark and a checksum. `cOptPtr` is optional : NULL can be provided, in which case all options will be set to default. @return : nb of bytes written into dstBuffer, necessarily >= 4 (endMark), or an error code if it fails (which can be tested using LZ4F_isError()) Note : LZ4F_compressEnd() is guaranteed to be successful when dstCapacity >= LZ4F_compressBound(0, prefsPtr). A successful call to LZ4F_compressEnd() makes `cctx` available again for another compression task.
typedef struct { unsigned stableDst; /* pledges that last 64KB decompressed data will remain available unmodified. This optimization skips storage operations in tmp buffers. */ unsigned reserved[3]; /* must be set to zero for forward compatibility */ } LZ4F_decompressOptions_t;
LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_dctx** dctxPtr, unsigned version); LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx);Create an LZ4F_dctx object, to track all decompression operations. The version provided MUST be LZ4F_VERSION. The function provides a pointer to an allocated and initialized LZ4F_dctx object. The result is an errorCode, which can be tested using LZ4F_isError(). dctx memory can be released using LZ4F_freeDecompressionContext(); Result of LZ4F_freeDecompressionContext() indicates current state of decompressionContext when being released. That is, it should be == 0 if decompression has been completed fully and correctly.
size_t LZ4F_getFrameInfo(LZ4F_dctx* dctx, LZ4F_frameInfo_t* frameInfoPtr, const void* srcBuffer, size_t* srcSizePtr);This function extracts frame parameters (max blockSize, dictID, etc.). Its usage is optional. Extracted information is typically useful for allocation and dictionary. This function works in 2 situations : - At the beginning of a new frame, in which case it will decode information from `srcBuffer`, starting the decoding process. Input size must be large enough to successfully decode the entire frame header. Frame header size is variable, but is guaranteed to be <= LZ4F_HEADER_SIZE_MAX bytes. It's allowed to provide more input data than this minimum. - After decoding has been started. In which case, no input is read, frame parameters are extracted from dctx. - If decoding has barely started, but not yet extracted information from header, LZ4F_getFrameInfo() will fail. The number of bytes consumed from srcBuffer will be updated within *srcSizePtr (necessarily <= original value). Decompression must resume from (srcBuffer + *srcSizePtr). @return : an hint about how many srcSize bytes LZ4F_decompress() expects for next call, or an error code which can be tested using LZ4F_isError(). note 1 : in case of error, dctx is not modified. Decoding operation can resume from beginning safely. note 2 : frame parameters are *copied into* an already allocated LZ4F_frameInfo_t structure.
size_t LZ4F_decompress(LZ4F_dctx* dctx, void* dstBuffer, size_t* dstSizePtr, const void* srcBuffer, size_t* srcSizePtr, const LZ4F_decompressOptions_t* dOptPtr);Call this function repetitively to regenerate compressed data from `srcBuffer`. The function will read up to *srcSizePtr bytes from srcBuffer, and decompress data into dstBuffer, of capacity *dstSizePtr. The nb of bytes consumed from srcBuffer will be written into *srcSizePtr (necessarily <= original value). The nb of bytes decompressed into dstBuffer will be written into *dstSizePtr (necessarily <= original value). The function does not necessarily read all input bytes, so always check value in *srcSizePtr. Unconsumed source data must be presented again in subsequent invocations. `dstBuffer` can freely change between each consecutive function invocation. `dstBuffer` content will be overwritten. @return : an hint of how many `srcSize` bytes LZ4F_decompress() expects for next call. Schematically, it's the size of the current (or remaining) compressed block + header of next block. Respecting the hint provides some small speed benefit, because it skips intermediate buffers. This is just a hint though, it's always possible to provide any srcSize. When a frame is fully decoded, @return will be 0 (no more data expected). When provided with more bytes than necessary to decode a frame, LZ4F_decompress() will stop reading exactly at end of current frame, and @return 0. If decompression failed, @return is an error code, which can be tested using LZ4F_isError(). After a decompression error, the `dctx` context is not resumable. Use LZ4F_resetDecompressionContext() to return to clean state. After a frame is fully decoded, dctx can be used again to decompress another frame.
void LZ4F_resetDecompressionContext(LZ4F_dctx* dctx); /* always successful */In case of an error, the context is left in "undefined" state. In which case, it's necessary to reset it, before re-using it. This method can also be used to abruptly stop any unfinished decompression, and start a new one using same context resources.
typedef enum { LZ4F_LIST_ERRORS(LZ4F_GENERATE_ENUM) _LZ4F_dummy_error_enum_for_c89_never_used } LZ4F_errorCodes;
LZ4FLIB_STATIC_API LZ4F_CDict* LZ4F_createCDict(const void* dictBuffer, size_t dictSize); LZ4FLIB_STATIC_API void LZ4F_freeCDict(LZ4F_CDict* CDict);When compressing multiple messages / blocks with the same dictionary, it's recommended to load it just once. LZ4_createCDict() will create a digested dictionary, ready to start future compression operations without startup delay. LZ4_CDict can be created once and shared by multiple threads concurrently, since its usage is read-only. `dictBuffer` can be released after LZ4_CDict creation, since its content is copied within CDict
LZ4FLIB_STATIC_API size_t LZ4F_compressFrame_usingCDict( LZ4F_cctx* cctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize, const LZ4F_CDict* cdict, const LZ4F_preferences_t* preferencesPtr);Compress an entire srcBuffer into a valid LZ4 frame using a digested Dictionary. cctx must point to a context created by LZ4F_createCompressionContext(). If cdict==NULL, compress without a dictionary. dstBuffer MUST be >= LZ4F_compressFrameBound(srcSize, preferencesPtr). If this condition is not respected, function will fail (@return an errorCode). The LZ4F_preferences_t structure is optional : you may provide NULL as argument, but it's not recommended, as it's the only way to provide dictID in the frame header. @return : number of bytes written into dstBuffer. or an error code if it fails (can be tested using LZ4F_isError())
LZ4FLIB_STATIC_API size_t LZ4F_compressBegin_usingCDict( LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_CDict* cdict, const LZ4F_preferences_t* prefsPtr);Inits streaming dictionary compression, and writes the frame header into dstBuffer. dstCapacity must be >= LZ4F_HEADER_SIZE_MAX bytes. `prefsPtr` is optional : you may provide NULL as argument, however, it's the only way to provide dictID in the frame header. @return : number of bytes written into dstBuffer for the header, or an error code (which can be tested using LZ4F_isError())
LZ4FLIB_STATIC_API size_t LZ4F_decompress_usingDict( LZ4F_dctx* dctxPtr, void* dstBuffer, size_t* dstSizePtr, const void* srcBuffer, size_t* srcSizePtr, const void* dict, size_t dictSize, const LZ4F_decompressOptions_t* decompressOptionsPtr);Same as LZ4F_decompress(), using a predefined dictionary. Dictionary is used "in place", without any preprocessing. It must remain accessible throughout the entire frame decoding.