290 lines
16 KiB
HTML
290 lines
16 KiB
HTML
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
<title>1.8.2 Manual</title>
|
|
</head>
|
|
<body>
|
|
<h1>1.8.2 Manual</h1>
|
|
<hr>
|
|
<a name="Contents"></a><h2>Contents</h2>
|
|
<ol>
|
|
<li><a href="#Chapter1">Introduction</a></li>
|
|
<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>
|
|
</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>
|
|
|
|
<a name="Chapter2"></a><h2>Compiler specifics</h2><pre></pre>
|
|
|
|
<a name="Chapter3"></a><h2>Error management</h2><pre></pre>
|
|
|
|
<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>
|
|
<a name="Chapter4"></a><h2>Frame compression types</h2><pre></pre>
|
|
|
|
<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_noBlockChecksum=0,
|
|
LZ4F_blockChecksumEnabled
|
|
} LZ4F_blockChecksum_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>/* LZ4F_blockLinked, LZ4F_blockIndependent ; 0 == default */<b>
|
|
LZ4F_contentChecksum_t contentChecksumFlag; </b>/* if enabled, frame is terminated with a 32-bits checksum of decompressed data ; 0 == disabled (default) */<b>
|
|
LZ4F_frameType_t frameType; </b>/* read-only field : LZ4F_frame or LZ4F_skippableFrame */<b>
|
|
unsigned long long contentSize; </b>/* Size of uncompressed content ; 0 == unknown */<b>
|
|
unsigned dictID; </b>/* Dictionary ID, sent by the compressor to help decoder select the correct dictionary; 0 == no dictID provided */<b>
|
|
LZ4F_blockChecksum_t blockChecksumFlag; </b>/* if enabled, each block is followed by a checksum of block's compressed data ; 0 == disabled (default) */<b>
|
|
} LZ4F_frameInfo_t;
|
|
</b><p> makes it possible to set or read frame parameters.
|
|
It's not required to set all fields, as long as the structure was initially memset() to zero.
|
|
For all fields, 0 sets it to default value
|
|
</p></pre><BR>
|
|
|
|
<pre><b>typedef struct {
|
|
LZ4F_frameInfo_t frameInfo;
|
|
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>
|
|
unsigned autoFlush; </b>/* 1 == always flush, to reduce usage of internal buffers */<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>
|
|
|
|
<a name="Chapter5"></a><h2>Simple compression function</h2><pre></pre>
|
|
|
|
<pre><b>size_t LZ4F_compressFrameBound(size_t srcSize, const LZ4F_preferences_t* preferencesPtr);
|
|
</b><p> 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.
|
|
|
|
</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.
|
|
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())
|
|
|
|
</p></pre><BR>
|
|
|
|
<a name="Chapter6"></a><h2>Advanced compression functions</h2><pre></pre>
|
|
|
|
<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>
|
|
<a name="Chapter7"></a><h2>Resource Management</h2><pre></pre>
|
|
|
|
<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.
|
|
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();
|
|
|
|
</p></pre><BR>
|
|
|
|
<a name="Chapter8"></a><h2>Compression</h2><pre></pre>
|
|
|
|
<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 >= 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 minimum dstCapacity required to guarantee compression success
|
|
given a srcSize and preferences, covering worst case scenario.
|
|
prefsPtr is optional : when NULL is provided, preferences will be set to cover worst case scenario.
|
|
Estimation is valid for either LZ4F_compressUpdate(), LZ4F_flush() or LZ4F_compressEnd(),
|
|
Estimation includes the possibility that internal buffer might already be filled by up to (blockSize-1) bytes.
|
|
It also includes frame footer (ending + checksum), which would have to be generated by LZ4F_compressEnd().
|
|
Estimation doesn't include frame header, as it was already generated by LZ4F_compressBegin().
|
|
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>
|
|
|
|
<a name="Chapter9"></a><h2>Decompression functions</h2><pre></pre>
|
|
|
|
<pre><b>typedef struct {
|
|
unsigned stableDst; </b>/* pledge that at least 64KB+64Bytes of previously decompressed data remain unmodifed where it was decoded. This optimization skips storage operations in tmp buffers */<b>
|
|
unsigned reserved[3]; </b>/* must be set to zero for forward compatibility */<b>
|
|
} LZ4F_decompressOptions_t;
|
|
</b></pre><BR>
|
|
<pre><b>LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_dctx** dctxPtr, unsigned version);
|
|
LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx);
|
|
</b><p> 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.
|
|
|
|
</p></pre><BR>
|
|
|
|
<a name="Chapter10"></a><h2>Streaming decompression functions</h2><pre></pre>
|
|
|
|
<pre><b>size_t LZ4F_getFrameInfo(LZ4F_dctx* dctx,
|
|
LZ4F_frameInfo_t* frameInfoPtr,
|
|
const void* srcBuffer, size_t* srcSizePtr);
|
|
</b><p> 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.
|
|
|
|
</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 compressed data from `srcBuffer`.
|
|
The function will read up to *srcSizePtr bytes from srcBuffer,
|
|
and decompress data into dstBuffer, of capacity *dstSizePtr.
|
|
|
|
The number of bytes consumed from srcBuffer will be written into *srcSizePtr (necessarily <= original value).
|
|
The number 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.
|
|
|
|
</p></pre><BR>
|
|
|
|
<pre><b>void LZ4F_resetDecompressionContext(LZ4F_dctx* dctx); </b>/* always successful */<b>
|
|
</b><p> 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.
|
|
</p></pre><BR>
|
|
|
|
</html>
|
|
</body>
|