From 3108eef8100c26d045275ab0ec9116a33c7f873a Mon Sep 17 00:00:00 2001 From: Yann Collet Date: Thu, 28 Aug 2014 10:14:33 +0100 Subject: lz4frame API update : introducing LZ4F_getHeaderInfo() --- lz4frame.h | 60 ++++++++++++++++++++++++------------------------------------ 1 file changed, 24 insertions(+), 36 deletions(-) diff --git a/lz4frame.h b/lz4frame.h index 45fdae3..240a81d 100644 --- a/lz4frame.h +++ b/lz4frame.h @@ -49,7 +49,8 @@ extern "C" { Error management **************************************/ typedef enum { - OK_NOERROR = 0, + OK_NoError = 0, + OK_FrameEnd = 1, ERROR_GENERIC = -1U, ERROR_maxDstSize_tooSmall = -2U, ERROR_compressionLevel_invalid = -3U, @@ -70,11 +71,11 @@ typedef enum { LZ4F_default=0, blockLinked, blockIndependent} blockMode_t; typedef enum { LZ4F_default=0, contentChecksumEnabled, noContentChecksum} contentChecksum_t; typedef struct { - unsigned compressionLevel; - maxBlockSize_t maxBlockSize; - blockMode_t blockMode; - contentChecksum_t contentChecksumFlag; - unsigned autoFlush; + unsigned compressionLevel; /* from 0 to 16 */ + maxBlockSize_t maxBlockSize; /* max64KB, max256KB, max1MB, max4MB ; 0 == default */ + blockMode_t blockMode; /* blockLinked, blockIndependent ; 0 == default */ + contentChecksum_t contentChecksumFlag; /* contentChecksumEnabled, noContentChecksum ; 0 == default */ + unsigned autoFlush; /* 1 == automatic flush after each call to LZ4F_compress() */ } LZ4F_preferences_t; @@ -107,14 +108,6 @@ typedef struct { int stableSrc; /* unused for the time being, must be 0 */ } LZ4F_compressOptions_t; -size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* preferences); -size_t LZ4F_getMaxSrcSize(size_t dstMaxSize, const LZ4F_preferences_t* preferences); -/* LZ4F_compressBound() : gives the size of Dst buffer given a srcSize to handle worst case situations. - * LZ4F_getMaxSrcSize() : gives max allowed srcSize given dstMaxSize to handle worst case situations. - * You can use dstMaxSize==0 to know the "natural" srcSize instead (block size). - * The LZ4F_preferences_t structure is optional : you can provide NULL as argument, all preferences will then be set to default. - */ - /* Resource Management */ #define LZ4F_VERSION 100 @@ -141,6 +134,14 @@ size_t LZ4F_compressBegin(LZ4F_compressionContext_t* compressionContextPtr, void * or an error code (can be tested using LZ4F_isError()) */ +size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* preferences); +size_t LZ4F_getMaxSrcSize(size_t dstMaxSize, const LZ4F_preferences_t* preferences); +/* LZ4F_compressBound() : gives the size of Dst buffer given a srcSize to handle worst case situations. + * LZ4F_getMaxSrcSize() : gives max allowed srcSize given dstMaxSize to handle worst case situations. + * You can use dstMaxSize==0 to know the "natural" srcSize instead (block size). + * The LZ4F_preferences_t structure is optional : you can provide NULL as argument, all preferences will then be set to default. + */ + 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. @@ -197,44 +198,31 @@ LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_compressionContext_t LZ4F_de * Object can release its memory using LZ4F_freeDecompressionContext(); */ -/* Header information */ +/* Decompression */ -LZ4F_errorCode_t LZ4F_analyzeHeader(LZ4F_decompressionContext_t* decompressionContextPtr, void* srcBuffer, size_t* srcSize); -/* LZ4F_analyzeHeader() - * +LZ4F_errorCode_t LZ4F_getHeaderInfo(LZ4F_preferences_t headerInfo, LZ4F_decompressionContext_t* decompressionContextPtr, void* srcBuffer, size_t* srcSize); +/* LZ4F_getHeaderInfo() * This function decodes header information, such as blockSize. - * LZ4F_analyzeHeader() is not compulsory. You could start instead by calling directly LZ4F_decompress. - * The objective is to only extract useful header information, without starting decompression. - * + * LZ4F_getHeaderInfo() is optional : you could start instead by calling directly LZ4F_decompress. + * The objective is to extract header information without starting decompression, typically for allocation purposes. + * LZ4F_getHeaderInfo() could also be used *after* starting decompression, on a valid frame decompression context. * The number of bytes read from srcBuffer will be provided within *srcSize (necessarily <= original value). - * * The function result is an error code which can be tested using LZ4F_isError(). */ -size_t LZ4F_getBlockSize(LZ4F_decompressionContext_t decompressionContext); -/* LZ4F_getBlockSize() - * Provides the maximum size of a (decompressed) block within previously analyzed frame. - * Primarily useful for memory allocation purposes. - * Header must be previously analyzed, using LZ4F_analyzeHeader(). - * - * The result is the maximum size of a single block, - * or an error code which can be tested using LZ4F_isError() in case of failure. - */ - -/* Decompression */ - LZ4F_errorCode_t LZ4F_decompress(LZ4F_decompressionContext_t decompressionContext, void* dstBuffer, size_t* dstSize, const void* srcBuffer, size_t* srcSize, const LZ4F_decompressOptions_t* decompressOptions); /* LZ4F_decompress() - * LZ4F_decompress() will be called repetitively to regenerate as much data as necessary. + * Call this function repetitively to regenerate data compressed within srcBuffer. * The function will attempt to decode *srcSize from srcBuffer, into dstBuffer of maximum size *dstSize. * * The number of bytes generated into dstBuffer will be provided within *dstSize (necessarily <= original value). * * The number of bytes effectively read from srcBuffer will be provided within *srcSize (necessarily <= original value). - * If the number of bytes read is < number of bytes provided, then the function could not complete decompression operation. + * If the number of bytes read is < number of bytes provided, then the decompression operation is not complete. * You will have to call it again, using the same src arguments (but eventually different dst arguments). * * The function result is an error code which can be tested using LZ4F_isError(). + * You'll be informed the frame is fully decoded on receiving result OK_FrameEnd(=1). */ -- cgit v0.12