2017-01-23 15:31:42 +00:00
|
|
|
<html>
|
|
|
|
|
<head>
|
|
|
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
2017-05-10 20:26:04 +00:00
|
|
|
<title>1.7.6 Manual</title>
|
2017-01-23 15:31:42 +00:00
|
|
|
</head>
|
|
|
|
|
<body>
|
2017-05-10 20:26:04 +00:00
|
|
|
<h1>1.7.6 Manual</h1>
|
2017-01-23 15:31:42 +00:00
|
|
|
<hr>
|
|
|
|
|
<a name="Contents"></a><h2>Contents</h2>
|
|
|
|
|
<ol>
|
|
|
|
|
<li><a href="#Chapter1">Introduction</a></li>
|
2017-05-10 20:26:04 +00:00
|
|
|
<li><a href="#Chapter2">Compiler specifics</a></li>
|
|
|
|
|
<li><a href="#Chapter3">Error management</a></li>
|
|
|
|
|
<li><a href="#Chapter4">Frame compression types</a></li>
|
|
|
|
|
<li><a href="#Chapter5">Simple compression function</a></li>
|
|
|
|
|
<li><a href="#Chapter6">Advanced compression functions</a></li>
|
|
|
|
|
<li><a href="#Chapter7">Resource Management</a></li>
|
|
|
|
|
<li><a href="#Chapter8">Compression</a></li>
|
|
|
|
|
<li><a href="#Chapter9">Decompression functions</a></li>
|
|
|
|
|
<li><a href="#Chapter10">Streaming decompression functions</a></li>
|
2017-01-23 15:31:42 +00:00
|
|
|
</ol>
|
|
|
|
|
<hr>
|
|
|
|
|
<a name="Chapter1"></a><h2>Introduction</h2><pre>
|
|
|
|
|
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.
|
|
|
|
|
<BR></pre>
|
|
|
|
|
|
2017-05-10 20:26:04 +00:00
|
|
|
<a name="Chapter2"></a><h2>Compiler specifics</h2><pre></pre>
|
|
|
|
|
|
|
|
|
|
<a name="Chapter3"></a><h2>Error management</h2><pre></pre>
|
2017-01-23 15:31:42 +00:00
|
|
|
|
|
|
|
|
<pre><b>unsigned LZ4F_isError(LZ4F_errorCode_t code); </b>/**< tells if a `LZ4F_errorCode_t` function result is an error code */<b>
|
|
|
|
|
</b></pre><BR>
|
|
|
|
|
<pre><b>const char* LZ4F_getErrorName(LZ4F_errorCode_t code); </b>/**< return error code string; useful for debugging */<b>
|
|
|
|
|
</b></pre><BR>
|
2017-05-10 20:26:04 +00:00
|
|
|
<a name="Chapter4"></a><h2>Frame compression types</h2><pre></pre>
|
2017-01-23 15:31:42 +00:00
|
|
|
|
|
|
|
|
<pre><b>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;
|
|
|
|
|
</b></pre><BR>
|
|
|
|
|
<pre><b>typedef enum {
|
|
|
|
|
LZ4F_blockLinked=0,
|
|
|
|
|
LZ4F_blockIndependent
|
|
|
|
|
LZ4F_OBSOLETE_ENUM(blockLinked)
|
|
|
|
|
LZ4F_OBSOLETE_ENUM(blockIndependent)
|
|
|
|
|
} LZ4F_blockMode_t;
|
|
|
|
|
</b></pre><BR>
|
|
|
|
|
<pre><b>typedef enum {
|
|
|
|
|
LZ4F_noContentChecksum=0,
|
|
|
|
|
LZ4F_contentChecksumEnabled
|
|
|
|
|
LZ4F_OBSOLETE_ENUM(noContentChecksum)
|
|
|
|
|
LZ4F_OBSOLETE_ENUM(contentChecksumEnabled)
|
|
|
|
|
} LZ4F_contentChecksum_t;
|
|
|
|
|
</b></pre><BR>
|
|
|
|
|
<pre><b>typedef enum {
|
|
|
|
|
LZ4F_frame=0,
|
|
|
|
|
LZ4F_skippableFrame
|
|
|
|
|
LZ4F_OBSOLETE_ENUM(skippableFrame)
|
|
|
|
|
} LZ4F_frameType_t;
|
|
|
|
|
</b></pre><BR>
|
|
|
|
|
<pre><b>typedef struct {
|
|
|
|
|
LZ4F_blockSizeID_t blockSizeID; </b>/* max64KB, max256KB, max1MB, max4MB ; 0 == default */<b>
|
|
|
|
|
LZ4F_blockMode_t blockMode; </b>/* blockLinked, blockIndependent ; 0 == default */<b>
|
|
|
|
|
LZ4F_contentChecksum_t contentChecksumFlag; </b>/* noContentChecksum, contentChecksumEnabled ; 0 == default */<b>
|
|
|
|
|
LZ4F_frameType_t frameType; </b>/* LZ4F_frame, skippableFrame ; 0 == default */<b>
|
|
|
|
|
unsigned long long contentSize; </b>/* Size of uncompressed (original) content ; 0 == unknown */<b>
|
|
|
|
|
unsigned reserved[2]; </b>/* must be zero for forward compatibility */<b>
|
|
|
|
|
} LZ4F_frameInfo_t;
|
|
|
|
|
</b><p> makes it possible to supply detailed frame parameters to the stream interface.
|
|
|
|
|
It's not required to set all fields, as long as the structure was initially memset() to zero.
|
|
|
|
|
All reserved fields must be set to zero.
|
|
|
|
|
</p></pre><BR>
|
|
|
|
|
|
|
|
|
|
<pre><b>typedef struct {
|
|
|
|
|
LZ4F_frameInfo_t frameInfo;
|
2017-05-10 20:26:04 +00:00
|
|
|
int compressionLevel; </b>/* 0 == default (fast mode); values above LZ4HC_CLEVEL_MAX count as LZ4HC_CLEVEL_MAX; values below 0 trigger "fast acceleration", proportional to value */<b>
|
2017-01-23 15:31:42 +00:00
|
|
|
unsigned autoFlush; </b>/* 1 == always flush (reduce usage of tmp buffer) */<b>
|
|
|
|
|
unsigned reserved[4]; </b>/* must be zero for forward compatibility */<b>
|
|
|
|
|
} LZ4F_preferences_t;
|
|
|
|
|
</b><p> makes it possible to supply detailed compression parameters to the stream interface.
|
|
|
|
|
It's not required to set all fields, as long as the structure was initially memset() to zero.
|
|
|
|
|
All reserved fields must be set to zero.
|
|
|
|
|
</p></pre><BR>
|
|
|
|
|
|
2017-05-10 20:26:04 +00:00
|
|
|
<a name="Chapter5"></a><h2>Simple compression function</h2><pre></pre>
|
2017-01-23 15:31:42 +00:00
|
|
|
|
|
|
|
|
<pre><b>size_t LZ4F_compressFrameBound(size_t srcSize, const LZ4F_preferences_t* preferencesPtr);
|
|
|
|
|
</b><p> 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.
|
|
|
|
|
|
|
|
|
|
</p></pre><BR>
|
|
|
|
|
|
|
|
|
|
<pre><b>size_t LZ4F_compressFrame(void* dstBuffer, size_t dstCapacity, const void* srcBuffer, size_t srcSize, const LZ4F_preferences_t* preferencesPtr);
|
|
|
|
|
</b><p> 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.
|
|
|
|
|
@return : number of bytes written into dstBuffer.
|
|
|
|
|
or an error code if it fails (can be tested using LZ4F_isError())
|
|
|
|
|
|
|
|
|
|
</p></pre><BR>
|
|
|
|
|
|
2017-05-10 20:26:04 +00:00
|
|
|
<a name="Chapter6"></a><h2>Advanced compression functions</h2><pre></pre>
|
2017-01-23 15:31:42 +00:00
|
|
|
|
|
|
|
|
<pre><b>typedef struct {
|
|
|
|
|
unsigned stableSrc; </b>/* 1 == src content will remain present on future calls to LZ4F_compress(); skip copying src content within tmp buffer */<b>
|
|
|
|
|
unsigned reserved[3];
|
|
|
|
|
} LZ4F_compressOptions_t;
|
|
|
|
|
</b></pre><BR>
|
2017-05-10 20:26:04 +00:00
|
|
|
<a name="Chapter7"></a><h2>Resource Management</h2><pre></pre>
|
|
|
|
|
|
2017-01-23 15:31:42 +00:00
|
|
|
<pre><b>LZ4F_errorCode_t LZ4F_createCompressionContext(LZ4F_cctx** cctxPtr, unsigned version);
|
|
|
|
|
LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx);
|
|
|
|
|
</b><p> The first thing to do is to create a compressionContext object, which will be used in all compression operations.
|
2017-05-10 20:26:04 +00:00
|
|
|
This is achieved using LZ4F_createCompressionContext(), which takes as argument a version.
|
2017-01-23 15:31:42 +00:00
|
|
|
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();
|
|
|
|
|
|
|
|
|
|
</p></pre><BR>
|
|
|
|
|
|
2017-05-10 20:26:04 +00:00
|
|
|
<a name="Chapter8"></a><h2>Compression</h2><pre></pre>
|
|
|
|
|
|
2017-01-23 15:31:42 +00:00
|
|
|
<pre><b>size_t LZ4F_compressBegin(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_preferences_t* prefsPtr);
|
|
|
|
|
</b><p> 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.
|
|
|
|
|
@return : number of bytes written into dstBuffer for the header
|
|
|
|
|
or an error code (which can be tested using LZ4F_isError())
|
|
|
|
|
|
|
|
|
|
</p></pre><BR>
|
|
|
|
|
|
|
|
|
|
<pre><b>size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr);
|
|
|
|
|
</b><p> 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.
|
|
|
|
|
|
|
|
|
|
</p></pre><BR>
|
|
|
|
|
|
|
|
|
|
<pre><b>size_t LZ4F_compressUpdate(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const void* srcBuffer, size_t srcSize, const LZ4F_compressOptions_t* cOptPtr);
|
|
|
|
|
</b><p> 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.
|
|
|
|
|
@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())
|
|
|
|
|
|
|
|
|
|
</p></pre><BR>
|
|
|
|
|
|
|
|
|
|
<pre><b>size_t LZ4F_flush(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_compressOptions_t* cOptPtr);
|
|
|
|
|
</b><p> 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 : 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())
|
|
|
|
|
|
|
|
|
|
</p></pre><BR>
|
|
|
|
|
|
|
|
|
|
<pre><b>size_t LZ4F_compressEnd(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_compressOptions_t* cOptPtr);
|
|
|
|
|
</b><p> 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 : 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 `cctx` available again for another compression task.
|
|
|
|
|
|
|
|
|
|
</p></pre><BR>
|
|
|
|
|
|
2017-05-10 20:26:04 +00:00
|
|
|
<a name="Chapter9"></a><h2>Decompression functions</h2><pre></pre>
|
2017-01-23 15:31:42 +00:00
|
|
|
|
|
|
|
|
<pre><b>typedef struct {
|
|
|
|
|
unsigned stableDst; </b>/* guarantee that decompressed data will still be there on next function calls (avoid storage into tmp buffers) */<b>
|
|
|
|
|
unsigned reserved[3];
|
|
|
|
|
} LZ4F_decompressOptions_t;
|
|
|
|
|
</b></pre><BR>
|
|
|
|
|
<pre><b>LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_dctx** dctxPtr, unsigned version);
|
2017-05-10 20:26:04 +00:00
|
|
|
LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx);
|
2017-01-23 15:31:42 +00:00
|
|
|
</b><p> Create an LZ4F_decompressionContext_t object, which will be used to track all decompression operations.
|
|
|
|
|
The version provided MUST be LZ4F_VERSION. It is intended to track potential breaking differences between different versions.
|
|
|
|
|
The function will provide a pointer to a fully allocated and initialized LZ4F_decompressionContext_t 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.
|
|
|
|
|
|
|
|
|
|
</p></pre><BR>
|
|
|
|
|
|
2017-05-10 20:26:04 +00:00
|
|
|
<a name="Chapter10"></a><h2>Streaming decompression functions</h2><pre></pre>
|
|
|
|
|
|
2017-01-23 15:31:42 +00:00
|
|
|
<pre><b>size_t LZ4F_getFrameInfo(LZ4F_dctx* dctx,
|
|
|
|
|
LZ4F_frameInfo_t* frameInfoPtr,
|
|
|
|
|
const void* srcBuffer, size_t* srcSizePtr);
|
2017-05-10 20:26:04 +00:00
|
|
|
</b><p> This function extracts frame parameters (such as max blockSize, frame checksum, etc.).
|
|
|
|
|
Its usage is optional. Extracted information can be useful for allocation purposes, typically.
|
|
|
|
|
This function works in 2 situations :
|
|
|
|
|
- At the beginning of a new frame, in which case it will decode this information from `srcBuffer`, and start 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 just started, but not yet extracted information from header, LZ4F_getFrameInfo() will fail.
|
2017-01-23 15:31:42 +00:00
|
|
|
The number of bytes consumed from srcBuffer will be updated within *srcSizePtr (necessarily <= original value).
|
2017-05-10 20:26:04 +00:00
|
|
|
Decompression must resume from (srcBuffer + *srcSizePtr).
|
2017-01-23 15:31:42 +00:00
|
|
|
@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()
|
2017-05-10 20:26:04 +00:00
|
|
|
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.
|
2017-01-23 15:31:42 +00:00
|
|
|
|
|
|
|
|
</p></pre><BR>
|
|
|
|
|
|
|
|
|
|
<pre><b>size_t LZ4F_decompress(LZ4F_dctx* dctx,
|
|
|
|
|
void* dstBuffer, size_t* dstSizePtr,
|
|
|
|
|
const void* srcBuffer, size_t* srcSizePtr,
|
|
|
|
|
const LZ4F_decompressOptions_t* dOptPtr);
|
|
|
|
|
</b><p> 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 read from srcBuffer will be provided within *srcSizePtr (necessarily <= original value).
|
|
|
|
|
Number of bytes read can be < number of bytes provided, meaning there is some more data to decode.
|
|
|
|
|
It typically happens when dstBuffer is not large enough to contain all decoded data.
|
|
|
|
|
Remaining data will have to be presented again in a subsequent invocation.
|
|
|
|
|
|
|
|
|
|
`dstBuffer` content is expected to be flushed between each invocation, as its content will be overwritten.
|
|
|
|
|
`dstBuffer` can be changed at will between each consecutive function invocation.
|
|
|
|
|
|
|
|
|
|
@return is 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.
|
2017-05-10 20:26:04 +00:00
|
|
|
Respecting the hint provides some small speed benefit, because it skips intermediate buffers.
|
2017-01-23 15:31:42 +00:00
|
|
|
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).
|
|
|
|
|
If decompression failed, @return 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.
|
2017-05-10 20:26:04 +00:00
|
|
|
After a decompression error, use LZ4F_resetDecompressionContext() before re-using dctx, to return to clean state.
|
2017-01-23 15:31:42 +00:00
|
|
|
|
|
|
|
|
</p></pre><BR>
|
|
|
|
|
|
2017-05-10 20:26:04 +00:00
|
|
|
<pre><b>LZ4F_errorCode_t LZ4F_resetDecompressionContext(LZ4F_dctx* dctx);
|
|
|
|
|
</b><p> When decompression ends successfully,
|
|
|
|
|
it's possible to start a new decompression immediately
|
|
|
|
|
re-using the same context.
|
|
|
|
|
However, 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 on the same context.
|
|
|
|
|
</p></pre><BR>
|
|
|
|
|
|
2017-01-23 15:31:42 +00:00
|
|
|
</html>
|
|
|
|
|
</body>
|
