#include <stddef.h>
Go to the source code of this file.
Classes | |
| struct | LZ4F_compressOptions_t |
| struct | LZ4F_decompressOptions_t |
| struct | LZ4F_frameInfo_t |
| struct | LZ4F_preferences_t |
Macros | |
| #define | LZ4F_DEPRECATE(x) x /* no deprecation warning for this compiler */ |
| #define | LZ4F_HEADER_SIZE_MAX 15 |
| #define | LZ4F_OBSOLETE_ENUM(x) , LZ4F_DEPRECATE(x) = LZ4F_##x |
| #define | LZ4F_VERSION 100 |
| #define | LZ4FLIB_API |
Typedefs | |
| typedef LZ4F_blockMode_t | blockMode_t |
| typedef LZ4F_blockSizeID_t | blockSizeID_t |
| typedef LZ4F_contentChecksum_t | contentChecksum_t |
| typedef LZ4F_frameType_t | frameType_t |
| typedef struct LZ4F_cctx_s | LZ4F_cctx |
| typedef LZ4F_cctx * | LZ4F_compressionContext_t |
| typedef struct LZ4F_dctx_s | LZ4F_dctx |
| typedef LZ4F_dctx * | LZ4F_decompressionContext_t |
| typedef size_t | LZ4F_errorCode_t |
Enumerations | |
| enum | LZ4F_blockMode_t { LZ4F_blockLinked =0, LZ4F_blockIndependent } |
| enum | LZ4F_blockSizeID_t { LZ4F_default =0, LZ4F_max64KB =4, LZ4F_max256KB =5, LZ4F_max1MB =6, LZ4F_max4MB =7 } |
| enum | LZ4F_contentChecksum_t { LZ4F_noContentChecksum =0, LZ4F_contentChecksumEnabled } |
| enum | LZ4F_frameType_t { LZ4F_frame =0, LZ4F_skippableFrame } |
Macro Definition Documentation
Definition at line 86 of file lz4frame.h.
| #define LZ4F_HEADER_SIZE_MAX 15 |
Definition at line 231 of file lz4frame.h.
| #define LZ4F_OBSOLETE_ENUM | ( | x | ) | , LZ4F_DEPRECATE(x) = LZ4F_##x |
Definition at line 105 of file lz4frame.h.
| #define LZ4F_VERSION 100 |
Definition at line 215 of file lz4frame.h.
| #define LZ4FLIB_API |
Introduction
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.
Definition at line 75 of file lz4frame.h.
Typedef Documentation
| typedef LZ4F_blockMode_t blockMode_t |
Definition at line 150 of file lz4frame.h.
| typedef LZ4F_blockSizeID_t blockSizeID_t |
Definition at line 149 of file lz4frame.h.
Definition at line 152 of file lz4frame.h.
| typedef LZ4F_frameType_t frameType_t |
Definition at line 151 of file lz4frame.h.
| typedef struct LZ4F_cctx_s LZ4F_cctx |
Definition at line 205 of file lz4frame.h.
| typedef LZ4F_cctx* LZ4F_compressionContext_t |
Definition at line 206 of file lz4frame.h.
| typedef struct LZ4F_dctx_s LZ4F_dctx |
Definition at line 286 of file lz4frame.h.
| typedef LZ4F_dctx* LZ4F_decompressionContext_t |
Definition at line 287 of file lz4frame.h.
| typedef size_t LZ4F_errorCode_t |
Definition at line 94 of file lz4frame.h.
Enumeration Type Documentation
| enum LZ4F_blockMode_t |
| Enumerator | |
|---|---|
| LZ4F_blockLinked | |
| LZ4F_blockIndependent | |
Definition at line 128 of file lz4frame.h.
| enum LZ4F_blockSizeID_t |
| Enumerator | |
|---|---|
| LZ4F_default | |
| LZ4F_max64KB | |
| LZ4F_max256KB | |
| LZ4F_max1MB | |
| LZ4F_max4MB | |
Definition at line 113 of file lz4frame.h.
| Enumerator | |
|---|---|
| LZ4F_noContentChecksum | |
| LZ4F_contentChecksumEnabled | |
Definition at line 135 of file lz4frame.h.
| enum LZ4F_frameType_t |
| Enumerator | |
|---|---|
| LZ4F_frame | |
| LZ4F_skippableFrame | |
Definition at line 142 of file lz4frame.h.
Function Documentation
| LZ4FLIB_API size_t LZ4F_compressBegin | ( | LZ4F_cctx * | cctxPtr, |
| void * | dstBuffer, | ||
| size_t | dstCapacity, | ||
| const LZ4F_preferences_t * | preferencesPtr | ||
| ) |
LZ4F_compressBegin() : will write the frame header into dstBuffer. dstCapacity must be large enough to store the header. Maximum header size is LZ4F_HEADER_SIZE_MAX bytes. prefsPtr is optional : you can provide NULL as argument, all preferences will then be set to default.
- Returns
- : number of bytes written into dstBuffer for the header or an error code (which can be tested using LZ4F_isError())
LZ4F_compressBegin() : will write the frame header into dstBuffer. dstBuffer must be large enough to accommodate a header (dstCapacity). Maximum header size is LZ4F_HEADER_SIZE_MAX bytes.
- Returns
- : number of bytes written into dstBuffer for the header or an error code (can be tested using LZ4F_isError())
Definition at line 416 of file lz4frame.c.
| LZ4FLIB_API size_t LZ4F_compressBound | ( | size_t | srcSize, |
| const LZ4F_preferences_t * | prefsPtr | ||
| ) |
LZ4F_compressBound() : Provides dstCapacity given a srcSize to guarantee operation success in worst case situations. prefsPtr is optional : you can provide NULL as argument, preferences will be set to cover worst case scenario. Result is always the same for a srcSize and prefsPtr, so it can be trusted to size reusable buffers. When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() operations.
Definition at line 499 of file lz4frame.c.
| LZ4FLIB_API size_t LZ4F_compressEnd | ( | LZ4F_cctx * | cctxPtr, |
| void * | dstBuffer, | ||
| size_t | dstMaxSize, | ||
| const LZ4F_compressOptions_t * | compressOptionsPtr | ||
| ) |
LZ4F_compressEnd() : 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.
- Returns
- : number of bytes written into dstBuffer (necessarily >= 4 (endMark), or 8 if optional frame checksum is enabled) or an error code if it fails (which can be tested using LZ4F_isError()) A successful call to LZ4F_compressEnd() makes
cctxavailable again for another compression task.
LZ4F_compressEnd() : When you want to properly finish the compressed frame, just call LZ4F_compressEnd(). It will flush whatever data remained within compressionContext (like LZ4_flush()) but also properly finalize the frame, with an endMark and a checksum. The result of the function is the number of bytes written into dstBuffer (necessarily >= 4 (endMark size)) The function outputs an error code if it fails (can be tested using LZ4F_isError()) The LZ4F_compressOptions_t structure is optional : you can provide NULL as argument. compressionContext can then be used again, starting with LZ4F_compressBegin(). The preferences will remain the same.
Definition at line 702 of file lz4frame.c.
| LZ4FLIB_API size_t LZ4F_compressFrame | ( | void * | dstBuffer, |
| size_t | dstCapacity, | ||
| const void * | srcBuffer, | ||
| size_t | srcSize, | ||
| const LZ4F_preferences_t * | preferencesPtr | ||
| ) |
LZ4F_compressFrame() : Compress an entire srcBuffer into a valid LZ4 frame, as defined by specification v1.5.1 An important rule is that dstBuffer MUST be large enough (dstCapacity) to store the result in worst case situation. This value is supplied by LZ4F_compressFrameBound(). If this condition is not respected, LZ4F_compressFrame() will fail (result is an errorCode). The LZ4F_preferences_t structure is optional : you can provide NULL as argument. All preferences will be set to default.
- Returns
- : number of bytes written into dstBuffer. or an error code if it fails (can be tested using LZ4F_isError())
LZ4F_compressFrame() : Compress an entire srcBuffer into a valid LZ4 frame, as defined by specification v1.5.0, in a single step. The most important rule is that dstBuffer MUST be large enough (dstCapacity) to ensure compression completion even in worst case. If this condition is not respected, LZ4F_compressFrame() will fail (result is an errorCode) Get the minimum value of dstCapacity by using LZ4F_compressFrameBound(). The LZ4F_preferences_t structure is optional : if NULL is provided as argument, preferences will be set to default. The result of the function is the number of bytes written into dstBuffer. The function outputs an error code if it fails (can be tested using LZ4F_isError())
Definition at line 313 of file lz4frame.c.
| LZ4FLIB_API size_t LZ4F_compressFrameBound | ( | size_t | srcSize, |
| const LZ4F_preferences_t * | preferencesPtr | ||
| ) |
LZ4F_compressFrameBound() : Returns the maximum possible size of a frame compressed with LZ4F_compressFrame() given srcSize content and preferences. Note : this result is only usable with LZ4F_compressFrame(), not with multi-segments compression.
Definition at line 291 of file lz4frame.c.
| LZ4FLIB_API size_t LZ4F_compressUpdate | ( | LZ4F_cctx * | cctxPtr, |
| void * | dstBuffer, | ||
| size_t | dstCapacity, | ||
| const void * | srcBuffer, | ||
| size_t | srcSize, | ||
| const LZ4F_compressOptions_t * | compressOptionsPtr | ||
| ) |
LZ4F_compressUpdate() : LZ4F_compressUpdate() can be called repetitively to compress as much data as necessary. An important rule is that 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.
- Returns
- : 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())
LZ4F_compressUpdate() : LZ4F_compressUpdate() can be called repetitively to compress as much data as necessary. The most important rule is that dstBuffer MUST be large enough (dstCapacity) to ensure compression completion even in worst case. If this condition is not respected, LZ4F_compress() will fail (result is an errorCode) You can get the minimum value of dstCapacity by using LZ4F_compressBound() The LZ4F_compressOptions_t structure is optional : you can provide NULL as argument. The result of the function is the number of bytes written into dstBuffer : it can be zero, meaning input data was just buffered. The function outputs an error code if it fails (can be tested using LZ4F_isError())
Definition at line 568 of file lz4frame.c.
| LZ4FLIB_API LZ4F_errorCode_t LZ4F_createCompressionContext | ( | LZ4F_cctx ** | cctxPtr, |
| unsigned | version | ||
| ) |
LZ4F_createCompressionContext() : 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
- Returns
- != zero, there was an error during context creation. Object can release its memory using LZ4F_freeCompressionContext();
| LZ4FLIB_API LZ4F_errorCode_t LZ4F_createDecompressionContext | ( | LZ4F_dctx ** | LZ4F_decompressionContextPtr, |
| unsigned | versionNumber | ||
| ) |
LZ4F_createDecompressionContext() : 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(); The result of LZ4F_freeDecompressionContext() is indicative of the current state of decompressionContext when being released. That is, it should be == 0 if decompression has been completed fully and correctly.
LZ4F_createDecompressionContext() : Create a decompressionContext object, which will track all decompression operations. Provides a pointer to a fully allocated and initialized LZ4F_decompressionContext object. Object can later be released using LZ4F_freeDecompressionContext().
- Returns
- : if != 0, there was an error during context creation.
Definition at line 763 of file lz4frame.c.
| LZ4FLIB_API size_t LZ4F_decompress | ( | LZ4F_dctx * | dctxPtr, |
| void * | dstBuffer, | ||
| size_t * | dstSizePtr, | ||
| const void * | srcBuffer, | ||
| size_t * | srcSizePtr, | ||
| const LZ4F_decompressOptions_t * | decompressOptionsPtr | ||
| ) |
LZ4F_decompress() : Call this function repetitively to regenerate compressed data from srcBuffer. The function will attempt to decode up to *srcSizePtr bytes from srcBuffer, into dstBuffer of capacity *dstSizePtr.
The number of bytes regenerated into dstBuffer is provided within *dstSizePtr (necessarily <= original value).
The number of bytes consumed from srcBuffer is provided within *srcSizePtr (necessarily <= original value). Number of bytes consumed can be < number of bytes provided. It typically happens when dstBuffer is not large enough to contain all decoded data. Unconsumed source data must be presented again in subsequent invocations.
dstBuffer content is expected to be flushed between each invocation, as its content will be overwritten. dstBuffer itself can be changed at will between each consecutive function invocation.
- Returns
- is an hint of how many
srcSizebytes 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, - will be 0 (no more data expected). If decompression failed,
- is an error code, which can be tested using LZ4F_isError().
After a frame is fully decoded, dctx can be used again to decompress another frame. After a decompression error, use LZ4F_resetDecompressionContext() before re-using dctx, to return to clean state.
LZ4F_decompress() : Call this function repetitively to regenerate data compressed within srcBuffer. The function will attempt to decode up to *srcSizePtr bytes from srcBuffer, into dstBuffer of capacity *dstSizePtr.
The number of bytes regenerated into dstBuffer will be provided within *dstSizePtr (necessarily <= original value).
The number of bytes effectively read from srcBuffer will be provided within *srcSizePtr (necessarily <= original value). If the number of bytes read is < number of bytes provided, then the decompression operation is not complete. Remaining data will have to be presented again in a subsequent invocation.
The function result is an hint of the better srcSize to use for next call to LZ4F_decompress. Basically, it's the size of the current (or remaining) compressed block + header of next block. Respecting the hint provides some boost to performance, since it allows less buffer shuffling. Note that this is just a hint, it's always possible to any srcSize value. When a frame is fully decoded,
- Returns
- will be 0. If decompression failed,
- is an error code which can be tested using LZ4F_isError().
Definition at line 1059 of file lz4frame.c.
| LZ4FLIB_API size_t LZ4F_flush | ( | LZ4F_cctx * | cctxPtr, |
| void * | dstBuffer, | ||
| size_t | dstCapacity, | ||
| const LZ4F_compressOptions_t * | compressOptionsPtr | ||
| ) |
LZ4F_flush() : 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.
- Returns
- : number of bytes written into dstBuffer (it can be zero, which means there was no data stored within cctx) or an error code if it fails (which can be tested using LZ4F_isError())
LZ4F_flush() : Should you need to create compressed data immediately, without waiting for a block to be filled, you can call LZ4_flush(), which will immediately compress any remaining data stored within compressionContext. The result of the function is the number of bytes written into dstBuffer (it can be zero, this means there was no data left within compressionContext) The function outputs an error code if it fails (can be tested using LZ4F_isError()) The LZ4F_compressOptions_t structure is optional : you can provide NULL as argument.
Definition at line 664 of file lz4frame.c.
| LZ4FLIB_API LZ4F_errorCode_t LZ4F_freeCompressionContext | ( | LZ4F_cctx * | cctx | ) |
| LZ4FLIB_API LZ4F_errorCode_t LZ4F_freeDecompressionContext | ( | LZ4F_dctx * | dctx | ) |
Definition at line 773 of file lz4frame.c.
| LZ4FLIB_API const char* LZ4F_getErrorName | ( | LZ4F_errorCode_t | code | ) |
return error code string; useful for debugging
Definition at line 197 of file lz4frame.c.
| LZ4FLIB_API size_t LZ4F_getFrameInfo | ( | LZ4F_dctx * | dctxPtr, |
| LZ4F_frameInfo_t * | frameInfoPtr, | ||
| const void * | srcBuffer, | ||
| size_t * | srcSizePtr | ||
| ) |
LZ4F_getFrameInfo() : This function extracts frame parameters (such as max blockSize, frame checksum, etc.). Its usage is optional. Extracted information can typically be useful for allocation purposes. 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).
- Returns
- : 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 safely. note 2 : frame parameters are copied into an already allocated LZ4F_frameInfo_t structure.
- At the beginning of a new frame, in which case it will decode this information from
srcBuffer, and start the decoding process. Amount of input data provided must be large enough to successfully decode the frame header. A header size is variable, but is guaranteed to be <= LZ4F_HEADER_SIZE_MAX bytes. It's possible 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. The number of bytes consumed from srcBuffer will be updated within *srcSizePtr (necessarily <= original value). Decompression must resume from (srcBuffer + *srcSizePtr).
- Returns
- : 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 operations can resume from where they stopped. note 2 : frame parameters are copied into an already allocated LZ4F_frameInfo_t structure.
Definition at line 933 of file lz4frame.c.
| LZ4FLIB_API unsigned LZ4F_getVersion | ( | void | ) |
Definition at line 217 of file lz4frame.c.
| LZ4FLIB_API unsigned LZ4F_isError | ( | LZ4F_errorCode_t | code | ) |
tells if a LZ4F_errorCode_t function result is an error code
Definition at line 192 of file lz4frame.c.
| LZ4FLIB_API void LZ4F_resetDecompressionContext | ( | LZ4F_dctx * | dctx | ) |
LZ4F_resetDecompressionContext() : v1.8.0 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 an unfinished decompression, and start a new one using the same context.
Definition at line 801 of file lz4frame.c.