259 lines
13 KiB
C
259 lines
13 KiB
C
/*
|
|
LZ4 auto-framing library
|
|
Header File
|
|
Copyright (C) 2011-2014, Yann Collet.
|
|
BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php)
|
|
|
|
Redistribution and use in source and binary forms, with or without
|
|
modification, are permitted provided that the following conditions are
|
|
met:
|
|
|
|
* Redistributions of source code must retain the above copyright
|
|
notice, this list of conditions and the following disclaimer.
|
|
* Redistributions in binary form must reproduce the above
|
|
copyright notice, this list of conditions and the following disclaimer
|
|
in the documentation and/or other materials provided with the
|
|
distribution.
|
|
|
|
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
|
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
|
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
|
|
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
|
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
|
|
You can contact the author at :
|
|
- LZ4 source repository : http://code.google.com/p/lz4/
|
|
- LZ4 public forum : https://groups.google.com/forum/#!forum/lz4c
|
|
*/
|
|
|
|
/* LZ4F is a stand-alone API to create LZ4-compressed frames
|
|
* fully conformant to specification v1.4.1.
|
|
* All related operations, including memory management, are handled by the library.
|
|
* You don't need lz4.h when using lz4frame.h.
|
|
* */
|
|
|
|
#pragma once
|
|
|
|
#if defined (__cplusplus)
|
|
extern "C" {
|
|
#endif
|
|
|
|
/****************************************
|
|
Note : experimental API.
|
|
Not yet integrated within lz4 library.
|
|
****************************************/
|
|
|
|
/**************************************
|
|
Includes
|
|
**************************************/
|
|
#include <stddef.h> /* size_t */
|
|
|
|
|
|
/**************************************
|
|
Error management
|
|
**************************************/
|
|
typedef size_t LZ4F_errorCode_t;
|
|
typedef enum { OK_FrameEnd = 1 } LZ4F_successCodes;
|
|
typedef enum { OK_NoError = 0, ERROR_GENERIC = 1,
|
|
ERROR_maxBlockSize_invalid, ERROR_blockMode_invalid, ERROR_contentChecksumFlag_invalid,
|
|
ERROR_compressionLevel_invalid,
|
|
ERROR_allocation_failed,
|
|
ERROR_srcSize_tooLarge, ERROR_dstMaxSize_tooSmall,
|
|
ERROR_checksum_invalid,
|
|
ERROR_maxCode
|
|
} LZ4F_errorCodes; /* error codes are negative unsigned values.
|
|
Compare function result to (-specificCode) */
|
|
|
|
int LZ4F_isError(LZ4F_errorCode_t code); /* Basically : code > -ERROR_maxCode */
|
|
|
|
|
|
/**************************************
|
|
Framing compression functions
|
|
**************************************/
|
|
|
|
typedef enum { LZ4F_default=0, max64KB=4, max256KB=5, max1MB=6, max4MB=7} blockSizeID_t;
|
|
typedef enum { blockLinked=0, blockIndependent} blockMode_t;
|
|
typedef enum { noContentChecksum=0, contentChecksumEnabled } contentChecksum_t;
|
|
|
|
typedef struct {
|
|
blockSizeID_t blockSizeID; /* max64KB, max256KB, max1MB, max4MB ; 0 == default */
|
|
blockMode_t blockMode; /* blockLinked, blockIndependent ; 0 == default */
|
|
contentChecksum_t contentChecksumFlag; /* noContentChecksum, contentChecksumEnabled ; 0 == default */
|
|
unsigned reserved[5];
|
|
} LZ4F_frameInfo_t;
|
|
|
|
typedef struct {
|
|
LZ4F_frameInfo_t frameInfo;
|
|
unsigned compressionLevel; /* from 0 to 16 */
|
|
unsigned autoFlush; /* 1 == always flush; reduce need for tmp buffer */
|
|
unsigned reserved[4];
|
|
} LZ4F_preferences_t;
|
|
|
|
|
|
|
|
/***********************************
|
|
* Simple compression function
|
|
* *********************************/
|
|
size_t LZ4F_compressFrameBound(size_t srcSize, const LZ4F_preferences_t* preferencesPtr);
|
|
|
|
size_t LZ4F_compressFrame(void* dstBuffer, size_t dstMaxSize, const void* srcBuffer, size_t srcSize, const LZ4F_preferences_t* preferencesPtr);
|
|
/* LZ4F_compressFrame()
|
|
* Compress an entire srcBuffer into a valid LZ4 frame, as defined by specification v1.4.1, in a single step.
|
|
* 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_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.
|
|
* The result of the function is the number of bytes written into dstBuffer.
|
|
* The function outputs an error code if it fails (can be tested using LZ4F_isError())
|
|
*/
|
|
|
|
|
|
|
|
/**********************************
|
|
* Advanced compression functions
|
|
* *********************************/
|
|
|
|
typedef void* LZ4F_compressionContext_t;
|
|
|
|
typedef struct {
|
|
unsigned stableSrc; /* 1 == src content will remain available on future calls to LZ4F_compress(); avoid saving src content within tmp buffer as future dictionary */
|
|
unsigned reserved[3];
|
|
} LZ4F_compressOptions_t;
|
|
|
|
/* Resource Management */
|
|
|
|
#define LZ4F_VERSION 100
|
|
LZ4F_errorCode_t LZ4F_createCompressionContext(LZ4F_compressionContext_t* LZ4F_compressionContextPtr, unsigned version);
|
|
LZ4F_errorCode_t 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 different binaries.
|
|
* The function will provide a pointer to a fully allocated LZ4F_compressionContext_t object.
|
|
* If the result LZ4F_errorCode_t is not zero, there was an error during context creation.
|
|
* Object can release its memory using LZ4F_freeCompressionContext();
|
|
*/
|
|
|
|
|
|
/* Compression */
|
|
|
|
size_t LZ4F_compressBegin(LZ4F_compressionContext_t compressionContext, void* dstBuffer, size_t dstMaxSize, const LZ4F_preferences_t* preferencesPtr);
|
|
/* LZ4F_compressBegin() :
|
|
* will write the frame header into dstBuffer.
|
|
* dstBuffer must be large enough to accommodate a header (dstMaxSize). Maximum header size is 19 bytes.
|
|
* The LZ4F_preferences_t structure is optional : you can provide NULL as argument, all preferences will then be set to default.
|
|
* 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_compressBound(size_t srcSize, const LZ4F_preferences_t* preferencesPtr);
|
|
/* LZ4F_compressBound() :
|
|
* Provides the minimum size of Dst buffer given srcSize to handle worst case situations.
|
|
* preferencesPtr is optional : you can provide NULL as argument, all preferences will then be set to default.
|
|
*/
|
|
|
|
size_t LZ4F_compressUpdate(LZ4F_compressionContext_t compressionContext, void* dstBuffer, size_t dstMaxSize, const void* srcBuffer, size_t srcSize, const LZ4F_compressOptions_t* compressOptionsPtr);
|
|
/* LZ4F_compressUpdate()
|
|
* LZ4F_compressUpdate() can be called repetitively to compress as much data as necessary.
|
|
* The most important rule is that dstBuffer MUST be large enough (dstMaxSize) to ensure compression completion even in worst case.
|
|
* If this condition is not respected, LZ4F_compress() will fail (result is an errorCode)
|
|
* You can get the minimum value of dstMaxSize by using LZ4F_compressBound()
|
|
* 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 was just buffered.
|
|
* 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, const LZ4F_compressOptions_t* compressOptionsPtr);
|
|
/* 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 buffered within compressionContext.
|
|
* 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, this means there was no data left within compressionContext)
|
|
* The function outputs an error code if it fails (can be tested using LZ4F_isError())
|
|
*/
|
|
|
|
size_t LZ4F_compressEnd(LZ4F_compressionContext_t compressionContext, void* dstBuffer, size_t dstMaxSize, const LZ4F_compressOptions_t* compressOptionsPtr);
|
|
/* 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.
|
|
* 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.
|
|
*/
|
|
|
|
|
|
/***********************************
|
|
* Decompression functions
|
|
* *********************************/
|
|
|
|
typedef void* LZ4F_decompressionContext_t;
|
|
|
|
typedef struct {
|
|
unsigned stableDst; /* unused for the time being, must be 0 */
|
|
unsigned reserved[3];
|
|
} LZ4F_decompressOptions_t;
|
|
|
|
/* Resource management */
|
|
|
|
LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_compressionContext_t* LZ4F_decompressionContextPtr, unsigned version);
|
|
LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_compressionContext_t LZ4F_decompressionContext);
|
|
/* LZ4F_createDecompressionContext() :
|
|
* The first thing to do is to create a decompressionContext object, which will be used in all decompression operations.
|
|
* This is achieved using LZ4F_createDecompressionContext().
|
|
* The function will provide a pointer to a fully allocated and initialized LZ4F_decompressionContext object.
|
|
* If the result LZ4F_errorCode_t is not OK_NoError, there was an error during context creation.
|
|
* Object can release its memory using LZ4F_freeDecompressionContext();
|
|
*/
|
|
|
|
/* Decompression */
|
|
|
|
size_t LZ4F_getFrameInfo(LZ4F_decompressionContext_t decompressionContext, LZ4F_frameInfo_t* frameInfoPtr, const void* srcBuffer, size_t* srcSizePtr);
|
|
/* LZ4F_getFrameInfo()
|
|
* This function decodes frame header information, such as blockSize.
|
|
* It is optional : you could start by calling directly LZ4F_decompress() instead.
|
|
* The objective is to extract header information without starting decompression, typically for allocation purposes.
|
|
* LZ4F_getFrameInfo() can also be used *after* starting decompression, on a valid LZ4F_decompressionContext_t.
|
|
* The number of bytes read from srcBuffer will be provided within *srcSizePtr (necessarily <= original value).
|
|
* You are expected to resume decompression from where it stopped (srcBuffer + *srcSizePtr)
|
|
* The function result is an hint of the better srcSize to use for next call to LZ4F_decompress,
|
|
* or an error code which can be tested using LZ4F_isError().
|
|
*/
|
|
|
|
size_t LZ4F_decompress(LZ4F_decompressionContext_t decompressionContext, void* dstBuffer, size_t* dstSizePtr, const void* srcBuffer, size_t* srcSizePtr, const LZ4F_decompressOptions_t* decompressOptionsPtr);
|
|
/* LZ4F_decompress()
|
|
* Call this function repetitively to regenerate data compressed within srcBuffer.
|
|
* The function will attempt to decode *srcSizePtr bytes from srcBuffer, into dstBuffer of maximum size *dstSizePtr.
|
|
*
|
|
* The number of bytes regenerated into dstBuffer will be provided within *dstSizePtr (necessarily <= original value).
|
|
*
|
|
* The number of bytes effectively used from srcBuffer will be provided within *srcSizePtr (necessarily <= original value).
|
|
* If the number of bytes read is < number of bytes provided, then the decompression operation is not complete.
|
|
* This typically happens when dstBuffer is not large enough to contain all decoded data.
|
|
* LZ4F_decompress() will have to be called again, starting from where it stopped (srcBuffer + *srcSizePtr)
|
|
* The function will check this condition, and refuse to continue if it is not respected.
|
|
* dstBuffer is supposed to be flushed between calls to the function, since its content will be rewritten.
|
|
* Different dst arguments can be used between each calls.
|
|
*
|
|
* The function result is an hint of the better srcSize to use for next call to LZ4F_decompress.
|
|
* Basically, 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 allows less buffer shuffling.
|
|
* Note that this is just a hint, you can always provide any srcSize you want.
|
|
* When a frame is fully decoded, the function result will be 0.
|
|
* If decompression failed, function result is an error code which can be tested using LZ4F_isError().
|
|
*/
|
|
|
|
|
|
|
|
#if defined (__cplusplus)
|
|
}
|
|
#endif
|