|
||||
File indexing completed on 2024-05-18 08:30:07
0001 /* 0002 LZ4F - LZ4-Frame library 0003 Header File 0004 Copyright (C) 2011-2020, Yann Collet. 0005 BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php) 0006 0007 Redistribution and use in source and binary forms, with or without 0008 modification, are permitted provided that the following conditions are 0009 met: 0010 0011 * Redistributions of source code must retain the above copyright 0012 notice, this list of conditions and the following disclaimer. 0013 * Redistributions in binary form must reproduce the above 0014 copyright notice, this list of conditions and the following disclaimer 0015 in the documentation and/or other materials provided with the 0016 distribution. 0017 0018 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 0019 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 0020 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 0021 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 0022 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 0023 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 0024 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 0025 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 0026 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 0027 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 0028 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 0029 0030 You can contact the author at : 0031 - LZ4 source repository : https://github.com/lz4/lz4 0032 - LZ4 public forum : https://groups.google.com/forum/#!forum/lz4c 0033 */ 0034 0035 /* LZ4F is a stand-alone API able to create and decode LZ4 frames 0036 * conformant with specification v1.6.1 in doc/lz4_Frame_format.md . 0037 * Generated frames are compatible with `lz4` CLI. 0038 * 0039 * LZ4F also offers streaming capabilities. 0040 * 0041 * lz4.h is not required when using lz4frame.h, 0042 * except to extract common constants such as LZ4_VERSION_NUMBER. 0043 * */ 0044 0045 #ifndef LZ4F_H_09782039843 0046 #define LZ4F_H_09782039843 0047 0048 #if defined (__cplusplus) 0049 extern "C" { 0050 #endif 0051 0052 /* --- Dependency --- */ 0053 #include <stddef.h> /* size_t */ 0054 0055 0056 /** 0057 * Introduction 0058 * 0059 * lz4frame.h implements LZ4 frame specification: see doc/lz4_Frame_format.md . 0060 * LZ4 Frames are compatible with `lz4` CLI, 0061 * and designed to be interoperable with any system. 0062 **/ 0063 0064 /*-*************************************************************** 0065 * Compiler specifics 0066 *****************************************************************/ 0067 /* LZ4_DLL_EXPORT : 0068 * Enable exporting of functions when building a Windows DLL 0069 * LZ4FLIB_VISIBILITY : 0070 * Control library symbols visibility. 0071 */ 0072 #ifndef LZ4FLIB_VISIBILITY 0073 # if defined(__GNUC__) && (__GNUC__ >= 4) 0074 # define LZ4FLIB_VISIBILITY __attribute__ ((visibility ("default"))) 0075 # else 0076 # define LZ4FLIB_VISIBILITY 0077 # endif 0078 #endif 0079 #if defined(LZ4_DLL_EXPORT) && (LZ4_DLL_EXPORT==1) 0080 # define LZ4FLIB_API __declspec(dllexport) LZ4FLIB_VISIBILITY 0081 #elif defined(LZ4_DLL_IMPORT) && (LZ4_DLL_IMPORT==1) 0082 # define LZ4FLIB_API __declspec(dllimport) LZ4FLIB_VISIBILITY 0083 #else 0084 # define LZ4FLIB_API LZ4FLIB_VISIBILITY 0085 #endif 0086 0087 #ifdef LZ4F_DISABLE_DEPRECATE_WARNINGS 0088 # define LZ4F_DEPRECATE(x) x 0089 #else 0090 # if defined(_MSC_VER) 0091 # define LZ4F_DEPRECATE(x) x /* __declspec(deprecated) x - only works with C++ */ 0092 # elif defined(__clang__) || (defined(__GNUC__) && (__GNUC__ >= 6)) 0093 # define LZ4F_DEPRECATE(x) x __attribute__((deprecated)) 0094 # else 0095 # define LZ4F_DEPRECATE(x) x /* no deprecation warning for this compiler */ 0096 # endif 0097 #endif 0098 0099 0100 /*-************************************ 0101 * Error management 0102 **************************************/ 0103 typedef size_t LZ4F_errorCode_t; 0104 0105 LZ4FLIB_API unsigned LZ4F_isError(LZ4F_errorCode_t code); /**< tells when a function result is an error code */ 0106 LZ4FLIB_API const char* LZ4F_getErrorName(LZ4F_errorCode_t code); /**< return error code string; for debugging */ 0107 0108 0109 /*-************************************ 0110 * Frame compression types 0111 ************************************* */ 0112 /* #define LZ4F_ENABLE_OBSOLETE_ENUMS // uncomment to enable obsolete enums */ 0113 #ifdef LZ4F_ENABLE_OBSOLETE_ENUMS 0114 # define LZ4F_OBSOLETE_ENUM(x) , LZ4F_DEPRECATE(x) = LZ4F_##x 0115 #else 0116 # define LZ4F_OBSOLETE_ENUM(x) 0117 #endif 0118 0119 /* The larger the block size, the (slightly) better the compression ratio, 0120 * though there are diminishing returns. 0121 * Larger blocks also increase memory usage on both compression and decompression sides. 0122 */ 0123 typedef enum { 0124 LZ4F_default=0, 0125 LZ4F_max64KB=4, 0126 LZ4F_max256KB=5, 0127 LZ4F_max1MB=6, 0128 LZ4F_max4MB=7 0129 LZ4F_OBSOLETE_ENUM(max64KB) 0130 LZ4F_OBSOLETE_ENUM(max256KB) 0131 LZ4F_OBSOLETE_ENUM(max1MB) 0132 LZ4F_OBSOLETE_ENUM(max4MB) 0133 } LZ4F_blockSizeID_t; 0134 0135 /* Linked blocks sharply reduce inefficiencies when using small blocks, 0136 * they compress better. 0137 * However, some LZ4 decoders are only compatible with independent blocks */ 0138 typedef enum { 0139 LZ4F_blockLinked=0, 0140 LZ4F_blockIndependent 0141 LZ4F_OBSOLETE_ENUM(blockLinked) 0142 LZ4F_OBSOLETE_ENUM(blockIndependent) 0143 } LZ4F_blockMode_t; 0144 0145 typedef enum { 0146 LZ4F_noContentChecksum=0, 0147 LZ4F_contentChecksumEnabled 0148 LZ4F_OBSOLETE_ENUM(noContentChecksum) 0149 LZ4F_OBSOLETE_ENUM(contentChecksumEnabled) 0150 } LZ4F_contentChecksum_t; 0151 0152 typedef enum { 0153 LZ4F_noBlockChecksum=0, 0154 LZ4F_blockChecksumEnabled 0155 } LZ4F_blockChecksum_t; 0156 0157 typedef enum { 0158 LZ4F_frame=0, 0159 LZ4F_skippableFrame 0160 LZ4F_OBSOLETE_ENUM(skippableFrame) 0161 } LZ4F_frameType_t; 0162 0163 #ifdef LZ4F_ENABLE_OBSOLETE_ENUMS 0164 typedef LZ4F_blockSizeID_t blockSizeID_t; 0165 typedef LZ4F_blockMode_t blockMode_t; 0166 typedef LZ4F_frameType_t frameType_t; 0167 typedef LZ4F_contentChecksum_t contentChecksum_t; 0168 #endif 0169 0170 /*! LZ4F_frameInfo_t : 0171 * makes it possible to set or read frame parameters. 0172 * Structure must be first init to 0, using memset() or LZ4F_INIT_FRAMEINFO, 0173 * setting all parameters to default. 0174 * It's then possible to update selectively some parameters */ 0175 typedef struct { 0176 LZ4F_blockSizeID_t blockSizeID; /* max64KB, max256KB, max1MB, max4MB; 0 == default */ 0177 LZ4F_blockMode_t blockMode; /* LZ4F_blockLinked, LZ4F_blockIndependent; 0 == default */ 0178 LZ4F_contentChecksum_t contentChecksumFlag; /* 1: frame terminated with 32-bit checksum of decompressed data; 0: disabled (default) */ 0179 LZ4F_frameType_t frameType; /* read-only field : LZ4F_frame or LZ4F_skippableFrame */ 0180 unsigned long long contentSize; /* Size of uncompressed content ; 0 == unknown */ 0181 unsigned dictID; /* Dictionary ID, sent by compressor to help decoder select correct dictionary; 0 == no dictID provided */ 0182 LZ4F_blockChecksum_t blockChecksumFlag; /* 1: each block followed by a checksum of block's compressed data; 0: disabled (default) */ 0183 } LZ4F_frameInfo_t; 0184 0185 #define LZ4F_INIT_FRAMEINFO { LZ4F_default, LZ4F_blockLinked, LZ4F_noContentChecksum, LZ4F_frame, 0ULL, 0U, LZ4F_noBlockChecksum } /* v1.8.3+ */ 0186 0187 /*! LZ4F_preferences_t : 0188 * makes it possible to supply advanced compression instructions to streaming interface. 0189 * Structure must be first init to 0, using memset() or LZ4F_INIT_PREFERENCES, 0190 * setting all parameters to default. 0191 * All reserved fields must be set to zero. */ 0192 typedef struct { 0193 LZ4F_frameInfo_t frameInfo; 0194 int compressionLevel; /* 0: default (fast mode); values > LZ4HC_CLEVEL_MAX count as LZ4HC_CLEVEL_MAX; values < 0 trigger "fast acceleration" */ 0195 unsigned autoFlush; /* 1: always flush; reduces usage of internal buffers */ 0196 unsigned favorDecSpeed; /* 1: parser favors decompression speed vs compression ratio. Only works for high compression modes (>= LZ4HC_CLEVEL_OPT_MIN) */ /* v1.8.2+ */ 0197 unsigned reserved[3]; /* must be zero for forward compatibility */ 0198 } LZ4F_preferences_t; 0199 0200 #define LZ4F_INIT_PREFERENCES { LZ4F_INIT_FRAMEINFO, 0, 0u, 0u, { 0u, 0u, 0u } } /* v1.8.3+ */ 0201 0202 0203 /*-********************************* 0204 * Simple compression function 0205 ***********************************/ 0206 0207 LZ4FLIB_API int LZ4F_compressionLevel_max(void); /* v1.8.0+ */ 0208 0209 /*! LZ4F_compressFrameBound() : 0210 * Returns the maximum possible compressed size with LZ4F_compressFrame() given srcSize and preferences. 0211 * `preferencesPtr` is optional. It can be replaced by NULL, in which case, the function will assume default preferences. 0212 * Note : this result is only usable with LZ4F_compressFrame(). 0213 * It may also be relevant to LZ4F_compressUpdate() _only if_ no flush() operation is ever performed. 0214 */ 0215 LZ4FLIB_API size_t LZ4F_compressFrameBound(size_t srcSize, const LZ4F_preferences_t* preferencesPtr); 0216 0217 /*! LZ4F_compressFrame() : 0218 * Compress an entire srcBuffer into a valid LZ4 frame. 0219 * dstCapacity MUST be >= LZ4F_compressFrameBound(srcSize, preferencesPtr). 0220 * The LZ4F_preferences_t structure is optional : you can provide NULL as argument. All preferences will be set to default. 0221 * @return : number of bytes written into dstBuffer. 0222 * or an error code if it fails (can be tested using LZ4F_isError()) 0223 */ 0224 LZ4FLIB_API size_t LZ4F_compressFrame(void* dstBuffer, size_t dstCapacity, 0225 const void* srcBuffer, size_t srcSize, 0226 const LZ4F_preferences_t* preferencesPtr); 0227 0228 0229 /*-*********************************** 0230 * Advanced compression functions 0231 *************************************/ 0232 typedef struct LZ4F_cctx_s LZ4F_cctx; /* incomplete type */ 0233 typedef LZ4F_cctx* LZ4F_compressionContext_t; /* for compatibility with older APIs, prefer using LZ4F_cctx */ 0234 0235 typedef struct { 0236 unsigned stableSrc; /* 1 == src content will remain present on future calls to LZ4F_compress(); skip copying src content within tmp buffer */ 0237 unsigned reserved[3]; 0238 } LZ4F_compressOptions_t; 0239 0240 /*--- Resource Management ---*/ 0241 0242 #define LZ4F_VERSION 100 /* This number can be used to check for an incompatible API breaking change */ 0243 LZ4FLIB_API unsigned LZ4F_getVersion(void); 0244 0245 /*! LZ4F_createCompressionContext() : 0246 * The first thing to do is to create a compressionContext object, 0247 * which will keep track of operation state during streaming compression. 0248 * This is achieved using LZ4F_createCompressionContext(), which takes as argument a version, 0249 * and a pointer to LZ4F_cctx*, to write the resulting pointer into. 0250 * @version provided MUST be LZ4F_VERSION. It is intended to track potential version mismatch, notably when using DLL. 0251 * The function provides a pointer to a fully allocated LZ4F_cctx object. 0252 * @cctxPtr MUST be != NULL. 0253 * If @return != zero, context creation failed. 0254 * A created compression context can be employed multiple times for consecutive streaming operations. 0255 * Once all streaming compression jobs are completed, 0256 * the state object can be released using LZ4F_freeCompressionContext(). 0257 * Note1 : LZ4F_freeCompressionContext() is always successful. Its return value can be ignored. 0258 * Note2 : LZ4F_freeCompressionContext() works fine with NULL input pointers (do nothing). 0259 **/ 0260 LZ4FLIB_API LZ4F_errorCode_t LZ4F_createCompressionContext(LZ4F_cctx** cctxPtr, unsigned version); 0261 LZ4FLIB_API LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx); 0262 0263 0264 /*---- Compression ----*/ 0265 0266 #define LZ4F_HEADER_SIZE_MIN 7 /* LZ4 Frame header size can vary, depending on selected parameters */ 0267 #define LZ4F_HEADER_SIZE_MAX 19 0268 0269 /* Size in bytes of a block header in little-endian format. Highest bit indicates if block data is uncompressed */ 0270 #define LZ4F_BLOCK_HEADER_SIZE 4 0271 0272 /* Size in bytes of a block checksum footer in little-endian format. */ 0273 #define LZ4F_BLOCK_CHECKSUM_SIZE 4 0274 0275 /* Size in bytes of the content checksum. */ 0276 #define LZ4F_CONTENT_CHECKSUM_SIZE 4 0277 0278 /*! LZ4F_compressBegin() : 0279 * will write the frame header into dstBuffer. 0280 * dstCapacity must be >= LZ4F_HEADER_SIZE_MAX bytes. 0281 * `prefsPtr` is optional : you can provide NULL as argument, all preferences will then be set to default. 0282 * @return : number of bytes written into dstBuffer for the header 0283 * or an error code (which can be tested using LZ4F_isError()) 0284 */ 0285 LZ4FLIB_API size_t LZ4F_compressBegin(LZ4F_cctx* cctx, 0286 void* dstBuffer, size_t dstCapacity, 0287 const LZ4F_preferences_t* prefsPtr); 0288 0289 /*! LZ4F_compressBound() : 0290 * Provides minimum dstCapacity required to guarantee success of 0291 * LZ4F_compressUpdate(), given a srcSize and preferences, for a worst case scenario. 0292 * When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() instead. 0293 * Note that the result is only valid for a single invocation of LZ4F_compressUpdate(). 0294 * When invoking LZ4F_compressUpdate() multiple times, 0295 * if the output buffer is gradually filled up instead of emptied and re-used from its start, 0296 * one must check if there is enough remaining capacity before each invocation, using LZ4F_compressBound(). 0297 * @return is always the same for a srcSize and prefsPtr. 0298 * prefsPtr is optional : when NULL is provided, preferences will be set to cover worst case scenario. 0299 * tech details : 0300 * @return if automatic flushing is not enabled, includes the possibility that internal buffer might already be filled by up to (blockSize-1) bytes. 0301 * It also includes frame footer (ending + checksum), since it might be generated by LZ4F_compressEnd(). 0302 * @return doesn't include frame header, as it was already generated by LZ4F_compressBegin(). 0303 */ 0304 LZ4FLIB_API size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr); 0305 0306 /*! LZ4F_compressUpdate() : 0307 * LZ4F_compressUpdate() can be called repetitively to compress as much data as necessary. 0308 * Important rule: dstCapacity MUST be large enough to ensure operation success even in worst case situations. 0309 * This value is provided by LZ4F_compressBound(). 0310 * If this condition is not respected, LZ4F_compress() will fail (result is an errorCode). 0311 * After an error, the state is left in a UB state, and must be re-initialized or freed. 0312 * If previously an uncompressed block was written, buffered data is flushed 0313 * before appending compressed data is continued. 0314 * `cOptPtr` is optional : NULL can be provided, in which case all options are set to default. 0315 * @return : number of bytes written into `dstBuffer` (it can be zero, meaning input data was just buffered). 0316 * or an error code if it fails (which can be tested using LZ4F_isError()) 0317 */ 0318 LZ4FLIB_API size_t LZ4F_compressUpdate(LZ4F_cctx* cctx, 0319 void* dstBuffer, size_t dstCapacity, 0320 const void* srcBuffer, size_t srcSize, 0321 const LZ4F_compressOptions_t* cOptPtr); 0322 0323 /*! LZ4F_flush() : 0324 * When data must be generated and sent immediately, without waiting for a block to be completely filled, 0325 * it's possible to call LZ4_flush(). It will immediately compress any data buffered within cctx. 0326 * `dstCapacity` must be large enough to ensure the operation will be successful. 0327 * `cOptPtr` is optional : it's possible to provide NULL, all options will be set to default. 0328 * @return : nb of bytes written into dstBuffer (can be zero, when there is no data stored within cctx) 0329 * or an error code if it fails (which can be tested using LZ4F_isError()) 0330 * Note : LZ4F_flush() is guaranteed to be successful when dstCapacity >= LZ4F_compressBound(0, prefsPtr). 0331 */ 0332 LZ4FLIB_API size_t LZ4F_flush(LZ4F_cctx* cctx, 0333 void* dstBuffer, size_t dstCapacity, 0334 const LZ4F_compressOptions_t* cOptPtr); 0335 0336 /*! LZ4F_compressEnd() : 0337 * To properly finish an LZ4 frame, invoke LZ4F_compressEnd(). 0338 * It will flush whatever data remained within `cctx` (like LZ4_flush()) 0339 * and properly finalize the frame, with an endMark and a checksum. 0340 * `cOptPtr` is optional : NULL can be provided, in which case all options will be set to default. 0341 * @return : nb of bytes written into dstBuffer, necessarily >= 4 (endMark), 0342 * or an error code if it fails (which can be tested using LZ4F_isError()) 0343 * Note : LZ4F_compressEnd() is guaranteed to be successful when dstCapacity >= LZ4F_compressBound(0, prefsPtr). 0344 * A successful call to LZ4F_compressEnd() makes `cctx` available again for another compression task. 0345 */ 0346 LZ4FLIB_API size_t LZ4F_compressEnd(LZ4F_cctx* cctx, 0347 void* dstBuffer, size_t dstCapacity, 0348 const LZ4F_compressOptions_t* cOptPtr); 0349 0350 0351 /*-********************************* 0352 * Decompression functions 0353 ***********************************/ 0354 typedef struct LZ4F_dctx_s LZ4F_dctx; /* incomplete type */ 0355 typedef LZ4F_dctx* LZ4F_decompressionContext_t; /* compatibility with previous API versions */ 0356 0357 typedef struct { 0358 unsigned stableDst; /* pledges that last 64KB decompressed data will remain available unmodified between invocations. 0359 * This optimization skips storage operations in tmp buffers. */ 0360 unsigned skipChecksums; /* disable checksum calculation and verification, even when one is present in frame, to save CPU time. 0361 * Setting this option to 1 once disables all checksums for the rest of the frame. */ 0362 unsigned reserved1; /* must be set to zero for forward compatibility */ 0363 unsigned reserved0; /* idem */ 0364 } LZ4F_decompressOptions_t; 0365 0366 0367 /* Resource management */ 0368 0369 /*! LZ4F_createDecompressionContext() : 0370 * Create an LZ4F_dctx object, to track all decompression operations. 0371 * @version provided MUST be LZ4F_VERSION. 0372 * @dctxPtr MUST be valid. 0373 * The function fills @dctxPtr with the value of a pointer to an allocated and initialized LZ4F_dctx object. 0374 * The @return is an errorCode, which can be tested using LZ4F_isError(). 0375 * dctx memory can be released using LZ4F_freeDecompressionContext(); 0376 * Result of LZ4F_freeDecompressionContext() indicates current state of decompressionContext when being released. 0377 * That is, it should be == 0 if decompression has been completed fully and correctly. 0378 */ 0379 LZ4FLIB_API LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_dctx** dctxPtr, unsigned version); 0380 LZ4FLIB_API LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx); 0381 0382 0383 /*-*********************************** 0384 * Streaming decompression functions 0385 *************************************/ 0386 0387 #define LZ4F_MAGICNUMBER 0x184D2204U 0388 #define LZ4F_MAGIC_SKIPPABLE_START 0x184D2A50U 0389 #define LZ4F_MIN_SIZE_TO_KNOW_HEADER_LENGTH 5 0390 0391 /*! LZ4F_headerSize() : v1.9.0+ 0392 * Provide the header size of a frame starting at `src`. 0393 * `srcSize` must be >= LZ4F_MIN_SIZE_TO_KNOW_HEADER_LENGTH, 0394 * which is enough to decode the header length. 0395 * @return : size of frame header 0396 * or an error code, which can be tested using LZ4F_isError() 0397 * note : Frame header size is variable, but is guaranteed to be 0398 * >= LZ4F_HEADER_SIZE_MIN bytes, and <= LZ4F_HEADER_SIZE_MAX bytes. 0399 */ 0400 LZ4FLIB_API size_t LZ4F_headerSize(const void* src, size_t srcSize); 0401 0402 /*! LZ4F_getFrameInfo() : 0403 * This function extracts frame parameters (max blockSize, dictID, etc.). 0404 * Its usage is optional: user can also invoke LZ4F_decompress() directly. 0405 * 0406 * Extracted information will fill an existing LZ4F_frameInfo_t structure. 0407 * This can be useful for allocation and dictionary identification purposes. 0408 * 0409 * LZ4F_getFrameInfo() can work in the following situations : 0410 * 0411 * 1) At the beginning of a new frame, before any invocation of LZ4F_decompress(). 0412 * It will decode header from `srcBuffer`, 0413 * consuming the header and starting the decoding process. 0414 * 0415 * Input size must be large enough to contain the full frame header. 0416 * Frame header size can be known beforehand by LZ4F_headerSize(). 0417 * Frame header size is variable, but is guaranteed to be >= LZ4F_HEADER_SIZE_MIN bytes, 0418 * and not more than <= LZ4F_HEADER_SIZE_MAX bytes. 0419 * Hence, blindly providing LZ4F_HEADER_SIZE_MAX bytes or more will always work. 0420 * It's allowed to provide more input data than the header size, 0421 * LZ4F_getFrameInfo() will only consume the header. 0422 * 0423 * If input size is not large enough, 0424 * aka if it's smaller than header size, 0425 * function will fail and return an error code. 0426 * 0427 * 2) After decoding has been started, 0428 * it's possible to invoke LZ4F_getFrameInfo() anytime 0429 * to extract already decoded frame parameters stored within dctx. 0430 * 0431 * Note that, if decoding has barely started, 0432 * and not yet read enough information to decode the header, 0433 * LZ4F_getFrameInfo() will fail. 0434 * 0435 * The number of bytes consumed from srcBuffer will be updated in *srcSizePtr (necessarily <= original value). 0436 * LZ4F_getFrameInfo() only consumes bytes when decoding has not yet started, 0437 * and when decoding the header has been successful. 0438 * Decompression must then resume from (srcBuffer + *srcSizePtr). 0439 * 0440 * @return : a hint about how many srcSize bytes LZ4F_decompress() expects for next call, 0441 * or an error code which can be tested using LZ4F_isError(). 0442 * note 1 : in case of error, dctx is not modified. Decoding operation can resume from beginning safely. 0443 * note 2 : frame parameters are *copied into* an already allocated LZ4F_frameInfo_t structure. 0444 */ 0445 LZ4FLIB_API size_t 0446 LZ4F_getFrameInfo(LZ4F_dctx* dctx, 0447 LZ4F_frameInfo_t* frameInfoPtr, 0448 const void* srcBuffer, size_t* srcSizePtr); 0449 0450 /*! LZ4F_decompress() : 0451 * Call this function repetitively to regenerate data compressed in `srcBuffer`. 0452 * 0453 * The function requires a valid dctx state. 0454 * It will read up to *srcSizePtr bytes from srcBuffer, 0455 * and decompress data into dstBuffer, of capacity *dstSizePtr. 0456 * 0457 * The nb of bytes consumed from srcBuffer will be written into *srcSizePtr (necessarily <= original value). 0458 * The nb of bytes decompressed into dstBuffer will be written into *dstSizePtr (necessarily <= original value). 0459 * 0460 * The function does not necessarily read all input bytes, so always check value in *srcSizePtr. 0461 * Unconsumed source data must be presented again in subsequent invocations. 0462 * 0463 * `dstBuffer` can freely change between each consecutive function invocation. 0464 * `dstBuffer` content will be overwritten. 0465 * 0466 * @return : an hint of how many `srcSize` bytes LZ4F_decompress() expects for next call. 0467 * Schematically, it's the size of the current (or remaining) compressed block + header of next block. 0468 * Respecting the hint provides some small speed benefit, because it skips intermediate buffers. 0469 * This is just a hint though, it's always possible to provide any srcSize. 0470 * 0471 * When a frame is fully decoded, @return will be 0 (no more data expected). 0472 * When provided with more bytes than necessary to decode a frame, 0473 * LZ4F_decompress() will stop reading exactly at end of current frame, and @return 0. 0474 * 0475 * If decompression failed, @return is an error code, which can be tested using LZ4F_isError(). 0476 * After a decompression error, the `dctx` context is not resumable. 0477 * Use LZ4F_resetDecompressionContext() to return to clean state. 0478 * 0479 * After a frame is fully decoded, dctx can be used again to decompress another frame. 0480 */ 0481 LZ4FLIB_API size_t 0482 LZ4F_decompress(LZ4F_dctx* dctx, 0483 void* dstBuffer, size_t* dstSizePtr, 0484 const void* srcBuffer, size_t* srcSizePtr, 0485 const LZ4F_decompressOptions_t* dOptPtr); 0486 0487 0488 /*! LZ4F_resetDecompressionContext() : added in v1.8.0 0489 * In case of an error, the context is left in "undefined" state. 0490 * In which case, it's necessary to reset it, before re-using it. 0491 * This method can also be used to abruptly stop any unfinished decompression, 0492 * and start a new one using same context resources. */ 0493 LZ4FLIB_API void LZ4F_resetDecompressionContext(LZ4F_dctx* dctx); /* always successful */ 0494 0495 0496 0497 #if defined (__cplusplus) 0498 } 0499 #endif 0500 0501 #endif /* LZ4F_H_09782039843 */ 0502 0503 #if defined(LZ4F_STATIC_LINKING_ONLY) && !defined(LZ4F_H_STATIC_09782039843) 0504 #define LZ4F_H_STATIC_09782039843 0505 0506 #if defined (__cplusplus) 0507 extern "C" { 0508 #endif 0509 0510 /* These declarations are not stable and may change in the future. 0511 * They are therefore only safe to depend on 0512 * when the caller is statically linked against the library. 0513 * To access their declarations, define LZ4F_STATIC_LINKING_ONLY. 0514 * 0515 * By default, these symbols aren't published into shared/dynamic libraries. 0516 * You can override this behavior and force them to be published 0517 * by defining LZ4F_PUBLISH_STATIC_FUNCTIONS. 0518 * Use at your own risk. 0519 */ 0520 #ifdef LZ4F_PUBLISH_STATIC_FUNCTIONS 0521 # define LZ4FLIB_STATIC_API LZ4FLIB_API 0522 #else 0523 # define LZ4FLIB_STATIC_API 0524 #endif 0525 0526 0527 /* --- Error List --- */ 0528 #define LZ4F_LIST_ERRORS(ITEM) \ 0529 ITEM(OK_NoError) \ 0530 ITEM(ERROR_GENERIC) \ 0531 ITEM(ERROR_maxBlockSize_invalid) \ 0532 ITEM(ERROR_blockMode_invalid) \ 0533 ITEM(ERROR_contentChecksumFlag_invalid) \ 0534 ITEM(ERROR_compressionLevel_invalid) \ 0535 ITEM(ERROR_headerVersion_wrong) \ 0536 ITEM(ERROR_blockChecksum_invalid) \ 0537 ITEM(ERROR_reservedFlag_set) \ 0538 ITEM(ERROR_allocation_failed) \ 0539 ITEM(ERROR_srcSize_tooLarge) \ 0540 ITEM(ERROR_dstMaxSize_tooSmall) \ 0541 ITEM(ERROR_frameHeader_incomplete) \ 0542 ITEM(ERROR_frameType_unknown) \ 0543 ITEM(ERROR_frameSize_wrong) \ 0544 ITEM(ERROR_srcPtr_wrong) \ 0545 ITEM(ERROR_decompressionFailed) \ 0546 ITEM(ERROR_headerChecksum_invalid) \ 0547 ITEM(ERROR_contentChecksum_invalid) \ 0548 ITEM(ERROR_frameDecoding_alreadyStarted) \ 0549 ITEM(ERROR_compressionState_uninitialized) \ 0550 ITEM(ERROR_parameter_null) \ 0551 ITEM(ERROR_maxCode) 0552 0553 #define LZ4F_GENERATE_ENUM(ENUM) LZ4F_##ENUM, 0554 0555 /* enum list is exposed, to handle specific errors */ 0556 typedef enum { LZ4F_LIST_ERRORS(LZ4F_GENERATE_ENUM) 0557 _LZ4F_dummy_error_enum_for_c89_never_used } LZ4F_errorCodes; 0558 0559 LZ4FLIB_STATIC_API LZ4F_errorCodes LZ4F_getErrorCode(size_t functionResult); 0560 0561 0562 /*! LZ4F_getBlockSize() : 0563 * Return, in scalar format (size_t), 0564 * the maximum block size associated with blockSizeID. 0565 **/ 0566 LZ4FLIB_STATIC_API size_t LZ4F_getBlockSize(LZ4F_blockSizeID_t blockSizeID); 0567 0568 /*! LZ4F_uncompressedUpdate() : 0569 * LZ4F_uncompressedUpdate() can be called repetitively to add as much data uncompressed data as necessary. 0570 * Important rule: dstCapacity MUST be large enough to store the entire source buffer as 0571 * no compression is done for this operation 0572 * If this condition is not respected, LZ4F_uncompressedUpdate() will fail (result is an errorCode). 0573 * After an error, the state is left in a UB state, and must be re-initialized or freed. 0574 * If previously a compressed block was written, buffered data is flushed 0575 * before appending uncompressed data is continued. 0576 * This is only supported when LZ4F_blockIndependent is used 0577 * `cOptPtr` is optional : NULL can be provided, in which case all options are set to default. 0578 * @return : number of bytes written into `dstBuffer` (it can be zero, meaning input data was just buffered). 0579 * or an error code if it fails (which can be tested using LZ4F_isError()) 0580 */ 0581 LZ4FLIB_STATIC_API size_t 0582 LZ4F_uncompressedUpdate(LZ4F_cctx* cctx, 0583 void* dstBuffer, size_t dstCapacity, 0584 const void* srcBuffer, size_t srcSize, 0585 const LZ4F_compressOptions_t* cOptPtr); 0586 0587 /********************************** 0588 * Bulk processing dictionary API 0589 *********************************/ 0590 0591 /* A Dictionary is useful for the compression of small messages (KB range). 0592 * It dramatically improves compression efficiency. 0593 * 0594 * LZ4 can ingest any input as dictionary, though only the last 64 KB are useful. 0595 * Best results are generally achieved by using Zstandard's Dictionary Builder 0596 * to generate a high-quality dictionary from a set of samples. 0597 * 0598 * Loading a dictionary has a cost, since it involves construction of tables. 0599 * The Bulk processing dictionary API makes it possible to share this cost 0600 * over an arbitrary number of compression jobs, even concurrently, 0601 * markedly improving compression latency for these cases. 0602 * 0603 * The same dictionary will have to be used on the decompression side 0604 * for decoding to be successful. 0605 * To help identify the correct dictionary at decoding stage, 0606 * the frame header allows optional embedding of a dictID field. 0607 */ 0608 typedef struct LZ4F_CDict_s LZ4F_CDict; 0609 0610 /*! LZ4_createCDict() : 0611 * When compressing multiple messages / blocks using the same dictionary, it's recommended to load it just once. 0612 * LZ4_createCDict() will create a digested dictionary, ready to start future compression operations without startup delay. 0613 * LZ4_CDict can be created once and shared by multiple threads concurrently, since its usage is read-only. 0614 * `dictBuffer` can be released after LZ4_CDict creation, since its content is copied within CDict */ 0615 LZ4FLIB_STATIC_API LZ4F_CDict* LZ4F_createCDict(const void* dictBuffer, size_t dictSize); 0616 LZ4FLIB_STATIC_API void LZ4F_freeCDict(LZ4F_CDict* CDict); 0617 0618 0619 /*! LZ4_compressFrame_usingCDict() : 0620 * Compress an entire srcBuffer into a valid LZ4 frame using a digested Dictionary. 0621 * cctx must point to a context created by LZ4F_createCompressionContext(). 0622 * If cdict==NULL, compress without a dictionary. 0623 * dstBuffer MUST be >= LZ4F_compressFrameBound(srcSize, preferencesPtr). 0624 * If this condition is not respected, function will fail (@return an errorCode). 0625 * The LZ4F_preferences_t structure is optional : you may provide NULL as argument, 0626 * but it's not recommended, as it's the only way to provide dictID in the frame header. 0627 * @return : number of bytes written into dstBuffer. 0628 * or an error code if it fails (can be tested using LZ4F_isError()) */ 0629 LZ4FLIB_STATIC_API size_t 0630 LZ4F_compressFrame_usingCDict(LZ4F_cctx* cctx, 0631 void* dst, size_t dstCapacity, 0632 const void* src, size_t srcSize, 0633 const LZ4F_CDict* cdict, 0634 const LZ4F_preferences_t* preferencesPtr); 0635 0636 0637 /*! LZ4F_compressBegin_usingCDict() : 0638 * Inits streaming dictionary compression, and writes the frame header into dstBuffer. 0639 * dstCapacity must be >= LZ4F_HEADER_SIZE_MAX bytes. 0640 * `prefsPtr` is optional : you may provide NULL as argument, 0641 * however, it's the only way to provide dictID in the frame header. 0642 * @return : number of bytes written into dstBuffer for the header, 0643 * or an error code (which can be tested using LZ4F_isError()) */ 0644 LZ4FLIB_STATIC_API size_t 0645 LZ4F_compressBegin_usingCDict(LZ4F_cctx* cctx, 0646 void* dstBuffer, size_t dstCapacity, 0647 const LZ4F_CDict* cdict, 0648 const LZ4F_preferences_t* prefsPtr); 0649 0650 0651 /*! LZ4F_decompress_usingDict() : 0652 * Same as LZ4F_decompress(), using a predefined dictionary. 0653 * Dictionary is used "in place", without any preprocessing. 0654 ** It must remain accessible throughout the entire frame decoding. */ 0655 LZ4FLIB_STATIC_API size_t 0656 LZ4F_decompress_usingDict(LZ4F_dctx* dctxPtr, 0657 void* dstBuffer, size_t* dstSizePtr, 0658 const void* srcBuffer, size_t* srcSizePtr, 0659 const void* dict, size_t dictSize, 0660 const LZ4F_decompressOptions_t* decompressOptionsPtr); 0661 0662 0663 /*! Custom memory allocation : 0664 * These prototypes make it possible to pass custom allocation/free functions. 0665 * LZ4F_customMem is provided at state creation time, using LZ4F_create*_advanced() listed below. 0666 * All allocation/free operations will be completed using these custom variants instead of regular <stdlib.h> ones. 0667 */ 0668 typedef void* (*LZ4F_AllocFunction) (void* opaqueState, size_t size); 0669 typedef void* (*LZ4F_CallocFunction) (void* opaqueState, size_t size); 0670 typedef void (*LZ4F_FreeFunction) (void* opaqueState, void* address); 0671 typedef struct { 0672 LZ4F_AllocFunction customAlloc; 0673 LZ4F_CallocFunction customCalloc; /* optional; when not defined, uses customAlloc + memset */ 0674 LZ4F_FreeFunction customFree; 0675 void* opaqueState; 0676 } LZ4F_CustomMem; 0677 static 0678 #ifdef __GNUC__ 0679 __attribute__((__unused__)) 0680 #endif 0681 LZ4F_CustomMem const LZ4F_defaultCMem = { NULL, NULL, NULL, NULL }; /**< this constant defers to stdlib's functions */ 0682 0683 LZ4FLIB_STATIC_API LZ4F_cctx* LZ4F_createCompressionContext_advanced(LZ4F_CustomMem customMem, unsigned version); 0684 LZ4FLIB_STATIC_API LZ4F_dctx* LZ4F_createDecompressionContext_advanced(LZ4F_CustomMem customMem, unsigned version); 0685 LZ4FLIB_STATIC_API LZ4F_CDict* LZ4F_createCDict_advanced(LZ4F_CustomMem customMem, const void* dictBuffer, size_t dictSize); 0686 0687 0688 #if defined (__cplusplus) 0689 } 0690 #endif 0691 0692 #endif /* defined(LZ4F_STATIC_LINKING_ONLY) && !defined(LZ4F_H_STATIC_09782039843) */
[ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
This page was automatically generated by the 2.3.5 LXR engine. The LXR team |