From 35946be11804d4fa46a60f4bb8326806f455eb5a Mon Sep 17 00:00:00 2001 From: Yann Collet Date: Sat, 23 Aug 2014 14:06:56 +0100 Subject: Updated LZ4F API : differentiate resource/compression functions --- lz4frame.h | 51 ++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 38 insertions(+), 13 deletions(-) diff --git a/lz4frame.h b/lz4frame.h index 3caa937..9e75207 100644 --- a/lz4frame.h +++ b/lz4frame.h @@ -71,31 +71,55 @@ typedef struct { } LZ4F_preferences_t; typedef struct { - int compressionLevel; /* default is compressionLevel value passed within preferences */ int autoFlush; /* default is 0 = no autoflush */ + 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 maxDstSize, 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. + */ -/* Main compression functions */ +/* ********************************* + * Compression functions + * *********************************/ -size_t LZ4F_compressInit(LZ4F_compressionContext_t* compressionContextPtr, void* dstBuffer, size_t dstMaxSize, const LZ4F_preferences_t* preferences); -/* LZ4F_compressInit() : - * 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. +/* Resource Management */ + +#define LZ4F_VERSION 100 +LZ4F_compressionContext_t LZ4F_createCompressionContext(int version, const LZ4F_preferences_t* preferences); +void LZ4F_freeCompressionContext(LZ4F_compressionContext_t* LZ4F_compressionContext); +/* LZ4F_createCompressionContext() : + * 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 differences between a program and an external dynamic library. * 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. + * The result of the function is a pointer to the LZ4F_compressionContext_t object. + * If the pointer is NULL, there was an error during context creation. + * Object can release its memory using LZ4F_freeCompressionContext(); + */ + + +/* Compression */ + +size_t LZ4F_compressBegin(LZ4F_compressionContext_t* compressionContextPtr, void* dstBuffer, size_t dstMaxSize); +/* LZ4F_compressBegin() : + * will write the frame header into dstBuffer. * 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()) + * 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() + * The most important rule is that dstBuffer MUST be large enough (dstMaxSize) to ensure compression completion even in worst case. + * You can get the minimum value 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. @@ -107,7 +131,8 @@ size_t LZ4F_flush(LZ4F_compressionContext_t compressionContext, void* dstBuffer, /* 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 result of the function is the number of bytes written into dstBuffer + * (it can be zero, this means 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. */ @@ -117,10 +142,10 @@ size_t LZ4F_compressEnd(LZ4F_compressionContext_t compressionContext, void* dstB * 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. + * compressionContext can then be used again, starting with LZ4F_compressBegin(). The preferences will remain the same. */ -- cgit v0.12