From f54c7e0e771e09ca6575148ea5a4bc4dd005e1d3 Mon Sep 17 00:00:00 2001 From: Przemyslaw Skibinski Date: Mon, 23 Jan 2017 16:31:42 +0100 Subject: added lz4frame_manual.html --- doc/lz4frame_manual.html | 240 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 240 insertions(+) create mode 100644 doc/lz4frame_manual.html diff --git a/doc/lz4frame_manual.html b/doc/lz4frame_manual.html new file mode 100644 index 0000000..f76ec3d --- /dev/null +++ b/doc/lz4frame_manual.html @@ -0,0 +1,240 @@ + + + +lz4frame 1.7.5 Manual + + +

lz4frame 1.7.5 Manual

Introduction
Error management
Frame compression types
Simple compression function
Advanced compression functions
Decompression functions

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.
+

+ +

Error management

+ +

unsigned    LZ4F_isError(LZ4F_errorCode_t code);   /**< tells if a `LZ4F_errorCode_t` function result is an error code */
+

const char* LZ4F_getErrorName(LZ4F_errorCode_t code);   /**< return error code string; useful for debugging */
+

Frame compression types

+ +

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_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;             /* blockLinked, blockIndependent ; 0 == default */
+  LZ4F_contentChecksum_t contentChecksumFlag;   /* noContentChecksum, contentChecksumEnabled ; 0 == default  */
+  LZ4F_frameType_t       frameType;             /* LZ4F_frame, skippableFrame ; 0 == default */
+  unsigned long long     contentSize;           /* Size of uncompressed (original) content ; 0 == unknown */
+  unsigned               reserved[2];           /* must be zero for forward compatibility */
+} LZ4F_frameInfo_t;
+ 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. 
+

+ +

typedef struct {
+  LZ4F_frameInfo_t frameInfo;
+  int      compressionLevel;       /* 0 == default (fast mode); values above 16 count as 16; values below 0 count as 0 */
+  unsigned autoFlush;              /* 1 == always flush (reduce usage of tmp buffer) */
+  unsigned reserved[4];            /* must be zero for forward compatibility */
+} LZ4F_preferences_t;
+ 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. 
+

+ +

Simple compression function

+ +

size_t LZ4F_compressFrameBound(size_t srcSize, const LZ4F_preferences_t* preferencesPtr);
+ 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.
+ 
+

+ +

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, 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())
+ 
+

+ +

Advanced compression functions

+ +

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 and an LZ4F_preferences_t structure.
+ 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 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())
+ 
+

+ +

size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr);
+ 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.
+ 
+

+ +

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.
+ 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())
+ 
+

+ +

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 : 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())
+ 
+

+ +

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 : 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.
+ 
+

+ +

Decompression functions

+ +

typedef struct {
+  unsigned stableDst;       /* guarantee that decompressed data will still be there on next function calls (avoid storage into tmp buffers) */
+  unsigned reserved[3];
+} LZ4F_decompressOptions_t;
+

LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_dctx** dctxPtr, unsigned version);
+LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* const dctx);
+ 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.
+ 
+

+ +

size_t LZ4F_getFrameInfo(LZ4F_dctx* dctx,
+                                     LZ4F_frameInfo_t* frameInfoPtr,
+                                     const void* srcBuffer, size_t* srcSizePtr);
+ This function decodes frame header information (such as max blockSize, frame checksum, etc.).
+ Its usage is optional. The objective is to extract frame header information, typically for allocation purposes.
+ A header size is variable and can length from 7 to 15 bytes. It's possible to provide more input bytes than that.
+ The number of bytes consumed from srcBuffer will be updated within *srcSizePtr (necessarily <= original value).
+ Decompression must resume from this point (srcBuffer + *srcSizePtr).
+ Note that LZ4F_getFrameInfo() can also be used anytime *after* decompression is started, in which case 0 input byte can be enough.
+ Frame header info is *copied into* an already allocated LZ4F_frameInfo_t structure.
+ @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()
+           (typically, when there is not enough src bytes to fully decode the frame header)
+ 
+

+ +

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 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.
+ Respecting the hint provides some boost to performance, since it does skip 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).
+ 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.
+ 
+

+ + + -- cgit v0.12