Added : lz4frame comments (doc)

diff --git a/lz4frame.h b/lz4frame.h
index 899bb09..7638953 100644 (file)
--- a/lz4frame.h
+++ b/lz4frame.h
@@ -41,7 +41,15 @@ extern "C" {
 /**************************************
    Error management
 **************************************/
-typedef enum { ERROR_GENERIC =-1U, ERROR_MIN = -2U } LZ4F_errorCode_t;
+typedef enum { 
+       ERROR_GENERIC                  = -1U, 
+       ERROR_maxDstSize_tooSmall      = -2U,
+    ERROR_compressionLevel_invalid = -3U,
+    ERROR_maxBlockSize_invalid     = -4U,
+    ERROR_blockMode_invalid        = -5U,
+    ERROR_contentChecksumFlag_invalid = -6U,
+       ERROR_MIN = -7U 
+       } LZ4F_errorCode_t;
 int LZ4F_isError(size_t code);
 
 
@@ -56,22 +64,64 @@ typedef enum { LZ4F_default=0, blockLinked, blockIndependent} blockMode_t;
 typedef enum { LZ4F_default=0, contentChecksumEnabled, contentNoChecksum} contentChecksum_t;
 
 typedef struct {
+  int               compressionLevel;   /* valid values are >= 0 */
   maxBlockSize_t    maxBlockSize;
   blockMode_t       blockMode;
-  contentChecksum_t contentChecksum;
+  contentChecksum_t contentChecksumFlag;
 } LZ4F_preferences_t;
 
-
-size_t LZ4F_createCompressionContext(LZ4F_compressionContext_t** compressionContextPtr, void* dstBuffer, size_t dstMaxSize, const LZ4F_preferences_t* preferences);
+typedef struct {
+  int compressionLevel;   /* default is compressionLevel value passed within preferences */
+  int autoFlush;          /* default is 0 = no autoflush */
+} LZ4F_compressOptions_t;
 
 size_t LZ4F_compressBound(size_t srcSize,    const LZ4F_preferences_t* preferences);
 size_t LZ4F_getMaxSrcSize(size_t maxDstSize, const LZ4F_preferences_t* preferences);
 
-size_t LZ4F_compress(LZ4F_compressionContext_t* compressionContext, void* dstBuffer, size_t dstMaxSize, const void* srcBuffer, size_t srcSize);
+
+/* Main compression functions */
+
+size_t LZ4F_compressInit(LZ4F_compressionContext_t** compressionContextPtr, void* dstBuffer, size_t dstMaxSize, const LZ4F_preferences_t* preferences);
+/* LZ4F_compress_Init() :
+ * The first thing to do is to create a compressionContext object.
+ * This is achieved using LZ4F_compressInit(), which takes as argument a dstBuffer and a LZ4F_preferences_t structure.
+ * The LZ4F_preferences_t structure is optional : you can provide NULL as argument, all preferences will then be set to default.
+ * The dstBuffer is required : LZ4F_compressInit() will write the frame header into it.
+ * dstBuffer must be large enough to accomodate a header (dstMaxSize). Maximum header size is 15 bytes.
+ * The result of the function is the number of bytes written into dstBuffer for the header, or an error code (can be tested using LZ4F_isError())
+ */
+
+size_t LZ4F_compress(LZ4F_compressionContext_t* compressionContext, void* dstBuffer, size_t dstMaxSize, const void* srcBuffer, size_t srcSize, const LZ4F_compressOptions_t* compressOptions);
+/* LZ4F_compress()
+ * You can then call LZ4F_compress() repetitively to compress as much data as necessary.
+ * The most important rule to keep in mind is that dstBuffer must be large enough (dstMaxSize) to ensure compression completion.
+ * You can know the minimum size of dstMaxSize by using LZ4F_compressBound()
+ * Conversely, given a fixed dstMaxSize value, you can know the maximum srcSize authorized using LZ4F_getMaxSrcSize()
+ * If this condition is not respected, LZ4F_compress() will fail (result is an errorCode)
+ * 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 is just stored within compressionContext for a future block to complete)
+ * The function outputs an error code if it fails (can be tested using LZ4F_isError())
+ */
        
-size_t LZ4F_flush(LZ4F_compressionContext_t* compressionContext, void* dstBuffer, size_t dstMaxSize);
+size_t LZ4F_flush(LZ4F_compressionContext_t* compressionContext, void* dstBuffer, size_t dstMaxSize, const LZ4F_compressOptions_t* compressOptions);
+/* 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 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.
+ */
        
-void   LZ4F_freeCompressionContext(LZ4F_compressionContext_t* compressionContext);
+size_t LZ4F_compressEnd(LZ4F_compressionContext_t* compressionContext, void* dstBuffer, size_t dstMaxSize, const LZ4F_compressOptions_t* compressOptions);
+/* 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.
+ * It will also free compressionContext memory, so you can't call LZ4F_compress() anymore afterwards.
+ * 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.
+ */
 
 
 #if defined (__cplusplus)