From 59b2c9df9d3c754295523ab79d2e99e7ba6d920b Mon Sep 17 00:00:00 2001 From: Yann Collet Date: Tue, 19 Aug 2014 17:24:37 +0100 Subject: [PATCH] Added : lz4frame comments (doc) --- lz4frame.h | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 57 insertions(+), 7 deletions(-) diff --git a/lz4frame.h b/lz4frame.h index 899bb09..7638953 100644 --- 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) -- 2.7.4