added lz4frame_manual.html

author: Przemyslaw Skibinski <inikep@gmail.com> 2017-01-23 15:31:42 (GMT)
committer: Przemyslaw Skibinski <inikep@gmail.com> 2017-01-23 15:31:42 (GMT)
commit: f54c7e0e771e09ca6575148ea5a4bc4dd005e1d3 (patch)
tree: ea923b0bdef6946b72fc767093ec6dfde9a2b40c /doc/lz4frame_manual.html
parent: 9071df0fa54ffad456dae41fe4463587cb6eeb4f (diff)
download: lz4-f54c7e0e771e09ca6575148ea5a4bc4dd005e1d3.zip
lz4-f54c7e0e771e09ca6575148ea5a4bc4dd005e1d3.tar.gz
lz4-f54c7e0e771e09ca6575148ea5a4bc4dd005e1d3.tar.bz2
1 files changed, 240 insertions, 0 deletions
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 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>lz4frame 1.7.5 Manual</title>
+</head>
+<body>
+<h1>lz4frame 1.7.5 Manual</h1>
+<hr>
+<a name="Contents"></a><h2>Contents</h2>
+<ol>
+<li><a href="#Chapter1">Introduction</a></li>
+<li><a href="#Chapter2">Error management</a></li>
+<li><a href="#Chapter3">Frame compression types</a></li>
+<li><a href="#Chapter4">Simple compression function</a></li>
+<li><a href="#Chapter5">Advanced compression functions</a></li>
+<li><a href="#Chapter6">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>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="Chapter3"></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_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;
+  int      compressionLevel;       </b>/* 0 == default (fast mode); values above 16 count as 16; values below 0 count as 0 */<b>
+  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>
+
+<a name="Chapter4"></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 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>
+
+<a name="Chapter5"></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>
+<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 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();
+ 
+</p></pre><BR>
+
+<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>
+
+<a name="Chapter6"></a><h2>Decompression functions</h2><pre></pre>
+
+<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);
+LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* const dctx);
+</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>
+
+<pre><b>size_t LZ4F_getFrameInfo(LZ4F_dctx* dctx,
+                                     LZ4F_frameInfo_t* frameInfoPtr,
+                                     const void* srcBuffer, size_t* srcSizePtr);
+</b><p> 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)
+ 
+</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.
+ 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.
+ 
+</p></pre><BR>
+
+</html>
+</body>
author	Przemyslaw Skibinski <inikep@gmail.com>	2017-01-23 15:31:42 (GMT)
committer	Przemyslaw Skibinski <inikep@gmail.com>	2017-01-23 15:31:42 (GMT)
commit	f54c7e0e771e09ca6575148ea5a4bc4dd005e1d3 (patch)
tree	ea923b0bdef6946b72fc767093ec6dfde9a2b40c /doc/lz4frame_manual.html
parent	9071df0fa54ffad456dae41fe4463587cb6eeb4f (diff)
download	lz4-f54c7e0e771e09ca6575148ea5a4bc4dd005e1d3.zip lz4-f54c7e0e771e09ca6575148ea5a4bc4dd005e1d3.tar.gz lz4-f54c7e0e771e09ca6575148ea5a4bc4dd005e1d3.tar.bz2