1 /* 2 LZ4 auto-framing library 3 Header File 4 Copyright (C) 2011-2017, Yann Collet. 5 BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php) 6 7 Redistribution and use in source and binary forms, with or without 8 modification, are permitted provided that the following conditions are 9 met: 10 11 * Redistributions of source code must retain the above copyright 12 notice, this list of conditions and the following disclaimer. 13 * Redistributions in binary form must reproduce the above 14 copyright notice, this list of conditions and the following disclaimer 15 in the documentation and/or other materials provided with the 16 distribution. 17 18 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 21 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 22 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 23 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 24 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 28 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 30 You can contact the author at : 31 - LZ4 source repository : https://github.com/lz4/lz4 32 - LZ4 public forum : https://groups.google.com/forum/#!forum/lz4c 33 */ 34 35 /* LZ4F is a stand-alone API to create LZ4-compressed frames 36 * conformant with specification v1.6.1. 37 * It also offers streaming capabilities. 38 * lz4.h is not required when using lz4frame.h, 39 * except to get constant such as LZ4_VERSION_NUMBER. 40 * */ 41 42 #ifndef LZ4F_H_09782039843 43 #define LZ4F_H_09782039843 44 45 #if defined (__cplusplus) 46 extern "C" { 47 #endif 48 49 /* --- Dependency --- */ 50 #include <stddef.h> /* size_t */ 51 52 53 /** 54 Introduction 55 56 lz4frame.h implements LZ4 frame specification (doc/lz4_Frame_format.md). 57 lz4frame.h provides frame compression functions that take care 58 of encoding standard metadata alongside LZ4-compressed blocks. 59 */ 60 61 /*-*************************************************************** 62 * Compiler specifics 63 *****************************************************************/ 64 /* LZ4_DLL_EXPORT : 65 * Enable exporting of functions when building a Windows DLL 66 * LZ4FLIB_API : 67 * Control library symbols visibility. 68 */ 69 #if defined(LZ4_DLL_EXPORT) && (LZ4_DLL_EXPORT==1) 70 # define LZ4FLIB_API __declspec(dllexport) 71 #elif defined(LZ4_DLL_IMPORT) && (LZ4_DLL_IMPORT==1) 72 # define LZ4FLIB_API __declspec(dllimport) 73 #elif defined(__GNUC__) && (__GNUC__ >= 4) 74 # define LZ4FLIB_API __attribute__ ((__visibility__ ("default"))) 75 #else 76 # define LZ4FLIB_API 77 #endif 78 79 #ifdef LZ4F_DISABLE_DEPRECATE_WARNINGS 80 # define LZ4F_DEPRECATE(x) x 81 #else 82 # if defined(_MSC_VER) 83 # define LZ4F_DEPRECATE(x) x /* __declspec(deprecated) x - only works with C++ */ 84 # elif defined(__clang__) || (defined(__GNUC__) && (__GNUC__ >= 6)) 85 # define LZ4F_DEPRECATE(x) x __attribute__((deprecated)) 86 # else 87 # define LZ4F_DEPRECATE(x) x /* no deprecation warning for this compiler */ 88 # endif 89 #endif 90 91 92 /*-************************************ 93 * Error management 94 **************************************/ 95 typedef size_t LZ4F_errorCode_t; 96 97 LZ4FLIB_API unsigned LZ4F_isError(LZ4F_errorCode_t code); /**< tells when a function result is an error code */ 98 LZ4FLIB_API const char* LZ4F_getErrorName(LZ4F_errorCode_t code); /**< return error code string; for debugging */ 99 100 101 /*-************************************ 102 * Frame compression types 103 **************************************/ 104 /* #define LZ4F_ENABLE_OBSOLETE_ENUMS // uncomment to enable obsolete enums */ 105 #ifdef LZ4F_ENABLE_OBSOLETE_ENUMS 106 # define LZ4F_OBSOLETE_ENUM(x) , LZ4F_DEPRECATE(x) = LZ4F_##x 107 #else 108 # define LZ4F_OBSOLETE_ENUM(x) 109 #endif 110 111 /* The larger the block size, the (slightly) better the compression ratio, 112 * though there are diminishing returns. 113 * Larger blocks also increase memory usage on both compression and decompression sides. */ 114 typedef enum { 115 LZ4F_default=0, 116 LZ4F_max64KB=4, 117 LZ4F_max256KB=5, 118 LZ4F_max1MB=6, 119 LZ4F_max4MB=7 120 LZ4F_OBSOLETE_ENUM(max64KB) 121 LZ4F_OBSOLETE_ENUM(max256KB) 122 LZ4F_OBSOLETE_ENUM(max1MB) 123 LZ4F_OBSOLETE_ENUM(max4MB) 124 } LZ4F_blockSizeID_t; 125 126 /* Linked blocks sharply reduce inefficiencies when using small blocks, 127 * they compress better. 128 * However, some LZ4 decoders are only compatible with independent blocks */ 129 typedef enum { 130 LZ4F_blockLinked=0, 131 LZ4F_blockIndependent 132 LZ4F_OBSOLETE_ENUM(blockLinked) 133 LZ4F_OBSOLETE_ENUM(blockIndependent) 134 } LZ4F_blockMode_t; 135 136 typedef enum { 137 LZ4F_noContentChecksum=0, 138 LZ4F_contentChecksumEnabled 139 LZ4F_OBSOLETE_ENUM(noContentChecksum) 140 LZ4F_OBSOLETE_ENUM(contentChecksumEnabled) 141 } LZ4F_contentChecksum_t; 142 143 typedef enum { 144 LZ4F_noBlockChecksum=0, 145 LZ4F_blockChecksumEnabled 146 } LZ4F_blockChecksum_t; 147 148 typedef enum { 149 LZ4F_frame=0, 150 LZ4F_skippableFrame 151 LZ4F_OBSOLETE_ENUM(skippableFrame) 152 } LZ4F_frameType_t; 153 154 #ifdef LZ4F_ENABLE_OBSOLETE_ENUMS 155 typedef LZ4F_blockSizeID_t blockSizeID_t; 156 typedef LZ4F_blockMode_t blockMode_t; 157 typedef LZ4F_frameType_t frameType_t; 158 typedef LZ4F_contentChecksum_t contentChecksum_t; 159 #endif 160 161 /*! LZ4F_frameInfo_t : 162 * makes it possible to set or read frame parameters. 163 * Structure must be first init to 0, using memset() or LZ4F_INIT_FRAMEINFO, 164 * setting all parameters to default. 165 * It's then possible to update selectively some parameters */ 166 typedef struct { 167 LZ4F_blockSizeID_t blockSizeID; /* max64KB, max256KB, max1MB, max4MB; 0 == default */ 168 LZ4F_blockMode_t blockMode; /* LZ4F_blockLinked, LZ4F_blockIndependent; 0 == default */ 169 LZ4F_contentChecksum_t contentChecksumFlag; /* 1: frame terminated with 32-bit checksum of decompressed data; 0: disabled (default) */ 170 LZ4F_frameType_t frameType; /* read-only field : LZ4F_frame or LZ4F_skippableFrame */ 171 unsigned long long contentSize; /* Size of uncompressed content ; 0 == unknown */ 172 unsigned dictID; /* Dictionary ID, sent by compressor to help decoder select correct dictionary; 0 == no dictID provided */ 173 LZ4F_blockChecksum_t blockChecksumFlag; /* 1: each block followed by a checksum of block's compressed data; 0: disabled (default) */ 174 } LZ4F_frameInfo_t; 175 176 #define LZ4F_INIT_FRAMEINFO { 0, 0, 0, 0, 0, 0, 0 } /* v1.8.3+ */ 177 178 /*! LZ4F_preferences_t : 179 * makes it possible to supply advanced compression instructions to streaming interface. 180 * Structure must be first init to 0, using memset() or LZ4F_INIT_PREFERENCES, 181 * setting all parameters to default. 182 * All reserved fields must be set to zero. */ 183 typedef struct { 184 LZ4F_frameInfo_t frameInfo; 185 int compressionLevel; /* 0: default (fast mode); values > LZ4HC_CLEVEL_MAX count as LZ4HC_CLEVEL_MAX; values < 0 trigger "fast acceleration" */ 186 unsigned autoFlush; /* 1: always flush; reduces usage of internal buffers */ 187 unsigned favorDecSpeed; /* 1: parser favors decompression speed vs compression ratio. Only works for high compression modes (>= LZ4HC_CLEVEL_OPT_MIN) */ /* v1.8.2+ */ 188 unsigned reserved[3]; /* must be zero for forward compatibility */ 189 } LZ4F_preferences_t; 190 191 #define LZ4F_INIT_PREFERENCES { LZ4F_INIT_FRAMEINFO, 0, 0, 0, { 0, 0, 0 } } /* v1.8.3+ */ 192 193 194 /*-********************************* 195 * Simple compression function 196 ***********************************/ 197 198 LZ4FLIB_API int LZ4F_compressionLevel_max(void); 199 200 /*! LZ4F_compressFrameBound() : 201 * Returns the maximum possible compressed size with LZ4F_compressFrame() given srcSize and preferences. 202 * `preferencesPtr` is optional. It can be replaced by NULL, in which case, the function will assume default preferences. 203 * Note : this result is only usable with LZ4F_compressFrame(). 204 * It may also be used with LZ4F_compressUpdate() _if no flush() operation_ is performed. 205 */ 206 LZ4FLIB_API size_t LZ4F_compressFrameBound(size_t srcSize, const LZ4F_preferences_t* preferencesPtr); 207 208 /*! LZ4F_compressFrame() : 209 * Compress an entire srcBuffer into a valid LZ4 frame. 210 * dstCapacity MUST be >= LZ4F_compressFrameBound(srcSize, preferencesPtr). 211 * The LZ4F_preferences_t structure is optional : you can provide NULL as argument. All preferences will be set to default. 212 * @return : number of bytes written into dstBuffer. 213 * or an error code if it fails (can be tested using LZ4F_isError()) 214 */ 215 LZ4FLIB_API size_t LZ4F_compressFrame(void* dstBuffer, size_t dstCapacity, 216 const void* srcBuffer, size_t srcSize, 217 const LZ4F_preferences_t* preferencesPtr); 218 219 220 /*-*********************************** 221 * Advanced compression functions 222 *************************************/ 223 typedef struct LZ4F_cctx_s LZ4F_cctx; /* incomplete type */ 224 typedef LZ4F_cctx* LZ4F_compressionContext_t; /* for compatibility with previous API version */ 225 226 typedef struct { 227 unsigned stableSrc; /* 1 == src content will remain present on future calls to LZ4F_compress(); skip copying src content within tmp buffer */ 228 unsigned reserved[3]; 229 } LZ4F_compressOptions_t; 230 231 /*--- Resource Management ---*/ 232 233 #define LZ4F_VERSION 100 /* This number can be used to check for an incompatible API breaking change */ 234 LZ4FLIB_API unsigned LZ4F_getVersion(void); 235 236 /*! LZ4F_createCompressionContext() : 237 * The first thing to do is to create a compressionContext object, which will be used in all compression operations. 238 * This is achieved using LZ4F_createCompressionContext(), which takes as argument a version. 239 * The version provided MUST be LZ4F_VERSION. It is intended to track potential version mismatch, notably when using DLL. 240 * The function will provide a pointer to a fully allocated LZ4F_cctx object. 241 * If @return != zero, there was an error during context creation. 242 * Object can release its memory using LZ4F_freeCompressionContext(); 243 */ 244 LZ4FLIB_API LZ4F_errorCode_t LZ4F_createCompressionContext(LZ4F_cctx** cctxPtr, unsigned version); 245 LZ4FLIB_API LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx); 246 247 248 /*---- Compression ----*/ 249 250 #define LZ4F_HEADER_SIZE_MAX 19 /* LZ4 Frame header size can vary from 7 to 19 bytes */ 251 /*! LZ4F_compressBegin() : 252 * will write the frame header into dstBuffer. 253 * dstCapacity must be >= LZ4F_HEADER_SIZE_MAX bytes. 254 * `prefsPtr` is optional : you can provide NULL as argument, all preferences will then be set to default. 255 * @return : number of bytes written into dstBuffer for the header 256 * or an error code (which can be tested using LZ4F_isError()) 257 */ 258 LZ4FLIB_API size_t LZ4F_compressBegin(LZ4F_cctx* cctx, 259 void* dstBuffer, size_t dstCapacity, 260 const LZ4F_preferences_t* prefsPtr); 261 262 /*! LZ4F_compressBound() : 263 * Provides minimum dstCapacity required to guarantee compression success 264 * given a srcSize and preferences, covering worst case scenario. 265 * prefsPtr is optional : when NULL is provided, preferences will be set to cover worst case scenario. 266 * Estimation is valid for either LZ4F_compressUpdate(), LZ4F_flush() or LZ4F_compressEnd(), 267 * Estimation includes the possibility that internal buffer might already be filled by up to (blockSize-1) bytes. 268 * It also includes frame footer (ending + checksum), which would have to be generated by LZ4F_compressEnd(). 269 * Estimation doesn't include frame header, as it was already generated by LZ4F_compressBegin(). 270 * Result is always the same for a srcSize and prefsPtr, so it can be trusted to size reusable buffers. 271 * When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() operations. 272 */ 273 LZ4FLIB_API size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr); 274 275 /*! LZ4F_compressUpdate() : 276 * LZ4F_compressUpdate() can be called repetitively to compress as much data as necessary. 277 * Important rule: dstCapacity MUST be large enough to ensure operation success even in worst case situations. 278 * This value is provided by LZ4F_compressBound(). 279 * If this condition is not respected, LZ4F_compress() will fail (result is an errorCode). 280 * LZ4F_compressUpdate() doesn't guarantee error recovery. 281 * When an error occurs, compression context must be freed or resized. 282 * `cOptPtr` is optional : NULL can be provided, in which case all options are set to default. 283 * @return : number of bytes written into `dstBuffer` (it can be zero, meaning input data was just buffered). 284 * or an error code if it fails (which can be tested using LZ4F_isError()) 285 */ 286 LZ4FLIB_API size_t LZ4F_compressUpdate(LZ4F_cctx* cctx, 287 void* dstBuffer, size_t dstCapacity, 288 const void* srcBuffer, size_t srcSize, 289 const LZ4F_compressOptions_t* cOptPtr); 290 291 /*! LZ4F_flush() : 292 * When data must be generated and sent immediately, without waiting for a block to be completely filled, 293 * it's possible to call LZ4_flush(). It will immediately compress any data buffered within cctx. 294 * `dstCapacity` must be large enough to ensure the operation will be successful. 295 * `cOptPtr` is optional : it's possible to provide NULL, all options will be set to default. 296 * @return : nb of bytes written into dstBuffer (can be zero, when there is no data stored within cctx) 297 * or an error code if it fails (which can be tested using LZ4F_isError()) 298 */ 299 LZ4FLIB_API size_t LZ4F_flush(LZ4F_cctx* cctx, 300 void* dstBuffer, size_t dstCapacity, 301 const LZ4F_compressOptions_t* cOptPtr); 302 303 /*! LZ4F_compressEnd() : 304 * To properly finish an LZ4 frame, invoke LZ4F_compressEnd(). 305 * It will flush whatever data remained within `cctx` (like LZ4_flush()) 306 * and properly finalize the frame, with an endMark and a checksum. 307 * `cOptPtr` is optional : NULL can be provided, in which case all options will be set to default. 308 * @return : nb of bytes written into dstBuffer, necessarily >= 4 (endMark), 309 * or an error code if it fails (which can be tested using LZ4F_isError()) 310 * A successful call to LZ4F_compressEnd() makes `cctx` available again for another compression task. 311 */ 312 LZ4FLIB_API size_t LZ4F_compressEnd(LZ4F_cctx* cctx, 313 void* dstBuffer, size_t dstCapacity, 314 const LZ4F_compressOptions_t* cOptPtr); 315 316 317 /*-********************************* 318 * Decompression functions 319 ***********************************/ 320 typedef struct LZ4F_dctx_s LZ4F_dctx; /* incomplete type */ 321 typedef LZ4F_dctx* LZ4F_decompressionContext_t; /* compatibility with previous API versions */ 322 323 typedef struct { 324 unsigned stableDst; /* pledges that last 64KB decompressed data will remain available unmodified. This optimization skips storage operations in tmp buffers. */ 325 unsigned reserved[3]; /* must be set to zero for forward compatibility */ 326 } LZ4F_decompressOptions_t; 327 328 329 /* Resource management */ 330 331 /*! LZ4F_createDecompressionContext() : 332 * Create an LZ4F_dctx object, to track all decompression operations. 333 * The version provided MUST be LZ4F_VERSION. 334 * The function provides a pointer to an allocated and initialized LZ4F_dctx object. 335 * The result is an errorCode, which can be tested using LZ4F_isError(). 336 * dctx memory can be released using LZ4F_freeDecompressionContext(); 337 * Result of LZ4F_freeDecompressionContext() indicates current state of decompressionContext when being released. 338 * That is, it should be == 0 if decompression has been completed fully and correctly. 339 */ 340 LZ4FLIB_API LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_dctx** dctxPtr, unsigned version); 341 LZ4FLIB_API LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx); 342 343 344 /*-*********************************** 345 * Streaming decompression functions 346 *************************************/ 347 348 /*! LZ4F_getFrameInfo() : 349 * This function extracts frame parameters (max blockSize, dictID, etc.). 350 * Its usage is optional. 351 * Extracted information is typically useful for allocation and dictionary. 352 * This function works in 2 situations : 353 * - At the beginning of a new frame, in which case 354 * it will decode information from `srcBuffer`, starting the decoding process. 355 * Input size must be large enough to successfully decode the entire frame header. 356 * Frame header size is variable, but is guaranteed to be <= LZ4F_HEADER_SIZE_MAX bytes. 357 * It's allowed to provide more input data than this minimum. 358 * - After decoding has been started. 359 * In which case, no input is read, frame parameters are extracted from dctx. 360 * - If decoding has barely started, but not yet extracted information from header, 361 * LZ4F_getFrameInfo() will fail. 362 * The number of bytes consumed from srcBuffer will be updated within *srcSizePtr (necessarily <= original value). 363 * Decompression must resume from (srcBuffer + *srcSizePtr). 364 * @return : an hint about how many srcSize bytes LZ4F_decompress() expects for next call, 365 * or an error code which can be tested using LZ4F_isError(). 366 * note 1 : in case of error, dctx is not modified. Decoding operation can resume from beginning safely. 367 * note 2 : frame parameters are *copied into* an already allocated LZ4F_frameInfo_t structure. 368 */ 369 LZ4FLIB_API size_t LZ4F_getFrameInfo(LZ4F_dctx* dctx, 370 LZ4F_frameInfo_t* frameInfoPtr, 371 const void* srcBuffer, size_t* srcSizePtr); 372 373 /*! LZ4F_decompress() : 374 * Call this function repetitively to regenerate compressed data from `srcBuffer`. 375 * The function will read up to *srcSizePtr bytes from srcBuffer, 376 * and decompress data into dstBuffer, of capacity *dstSizePtr. 377 * 378 * The nb of bytes consumed from srcBuffer will be written into *srcSizePtr (necessarily <= original value). 379 * The nb of bytes decompressed into dstBuffer will be written into *dstSizePtr (necessarily <= original value). 380 * 381 * The function does not necessarily read all input bytes, so always check value in *srcSizePtr. 382 * Unconsumed source data must be presented again in subsequent invocations. 383 * 384 * `dstBuffer` can freely change between each consecutive function invocation. 385 * `dstBuffer` content will be overwritten. 386 * 387 * @return : an hint of how many `srcSize` bytes LZ4F_decompress() expects for next call. 388 * Schematically, it's the size of the current (or remaining) compressed block + header of next block. 389 * Respecting the hint provides some small speed benefit, because it skips intermediate buffers. 390 * This is just a hint though, it's always possible to provide any srcSize. 391 * 392 * When a frame is fully decoded, @return will be 0 (no more data expected). 393 * When provided with more bytes than necessary to decode a frame, 394 * LZ4F_decompress() will stop reading exactly at end of current frame, and @return 0. 395 * 396 * If decompression failed, @return is an error code, which can be tested using LZ4F_isError(). 397 * After a decompression error, the `dctx` context is not resumable. 398 * Use LZ4F_resetDecompressionContext() to return to clean state. 399 * 400 * After a frame is fully decoded, dctx can be used again to decompress another frame. 401 */ 402 LZ4FLIB_API size_t LZ4F_decompress(LZ4F_dctx* dctx, 403 void* dstBuffer, size_t* dstSizePtr, 404 const void* srcBuffer, size_t* srcSizePtr, 405 const LZ4F_decompressOptions_t* dOptPtr); 406 407 408 /*! LZ4F_resetDecompressionContext() : added in v1.8.0 409 * In case of an error, the context is left in "undefined" state. 410 * In which case, it's necessary to reset it, before re-using it. 411 * This method can also be used to abruptly stop any unfinished decompression, 412 * and start a new one using same context resources. */ 413 LZ4FLIB_API void LZ4F_resetDecompressionContext(LZ4F_dctx* dctx); /* always successful */ 414 415 416 417 #if defined (__cplusplus) 418 } 419 #endif 420 421 #endif /* LZ4F_H_09782039843 */ 422 423 #if defined(LZ4F_STATIC_LINKING_ONLY) && !defined(LZ4F_H_STATIC_09782039843) 424 #define LZ4F_H_STATIC_09782039843 425 426 #if defined (__cplusplus) 427 extern "C" { 428 #endif 429 430 /* These declarations are not stable and may change in the future. They are 431 * therefore only safe to depend on when the caller is statically linked 432 * against the library. To access their declarations, define 433 * LZ4F_STATIC_LINKING_ONLY. 434 * 435 * There is a further protection mechanism where these symbols aren't published 436 * into shared/dynamic libraries. You can override this behavior and force 437 * them to be published by defining LZ4F_PUBLISH_STATIC_FUNCTIONS. Use at 438 * your own risk. 439 */ 440 #ifdef LZ4F_PUBLISH_STATIC_FUNCTIONS 441 #define LZ4FLIB_STATIC_API LZ4FLIB_API 442 #else 443 #define LZ4FLIB_STATIC_API 444 #endif 445 446 447 /* --- Error List --- */ 448 #define LZ4F_LIST_ERRORS(ITEM) \ 449 ITEM(OK_NoError) \ 450 ITEM(ERROR_GENERIC) \ 451 ITEM(ERROR_maxBlockSize_invalid) \ 452 ITEM(ERROR_blockMode_invalid) \ 453 ITEM(ERROR_contentChecksumFlag_invalid) \ 454 ITEM(ERROR_compressionLevel_invalid) \ 455 ITEM(ERROR_headerVersion_wrong) \ 456 ITEM(ERROR_blockChecksum_invalid) \ 457 ITEM(ERROR_reservedFlag_set) \ 458 ITEM(ERROR_allocation_failed) \ 459 ITEM(ERROR_srcSize_tooLarge) \ 460 ITEM(ERROR_dstMaxSize_tooSmall) \ 461 ITEM(ERROR_frameHeader_incomplete) \ 462 ITEM(ERROR_frameType_unknown) \ 463 ITEM(ERROR_frameSize_wrong) \ 464 ITEM(ERROR_srcPtr_wrong) \ 465 ITEM(ERROR_decompressionFailed) \ 466 ITEM(ERROR_headerChecksum_invalid) \ 467 ITEM(ERROR_contentChecksum_invalid) \ 468 ITEM(ERROR_frameDecoding_alreadyStarted) \ 469 ITEM(ERROR_maxCode) 470 471 #define LZ4F_GENERATE_ENUM(ENUM) LZ4F_##ENUM, 472 473 /* enum list is exposed, to handle specific errors */ 474 typedef enum { LZ4F_LIST_ERRORS(LZ4F_GENERATE_ENUM) } LZ4F_errorCodes; 475 476 LZ4FLIB_STATIC_API LZ4F_errorCodes LZ4F_getErrorCode(size_t functionResult); 477 478 479 480 /********************************** 481 * Bulk processing dictionary API 482 *********************************/ 483 typedef struct LZ4F_CDict_s LZ4F_CDict; 484 485 /*! LZ4_createCDict() : 486 * When compressing multiple messages / blocks with the same dictionary, it's recommended to load it just once. 487 * LZ4_createCDict() will create a digested dictionary, ready to start future compression operations without startup delay. 488 * LZ4_CDict can be created once and shared by multiple threads concurrently, since its usage is read-only. 489 * `dictBuffer` can be released after LZ4_CDict creation, since its content is copied within CDict */ 490 LZ4FLIB_STATIC_API LZ4F_CDict* LZ4F_createCDict(const void* dictBuffer, size_t dictSize); 491 LZ4FLIB_STATIC_API void LZ4F_freeCDict(LZ4F_CDict* CDict); 492 493 494 /*! LZ4_compressFrame_usingCDict() : 495 * Compress an entire srcBuffer into a valid LZ4 frame using a digested Dictionary. 496 * cctx must point to a context created by LZ4F_createCompressionContext(). 497 * If cdict==NULL, compress without a dictionary. 498 * dstBuffer MUST be >= LZ4F_compressFrameBound(srcSize, preferencesPtr). 499 * If this condition is not respected, function will fail (@return an errorCode). 500 * The LZ4F_preferences_t structure is optional : you may provide NULL as argument, 501 * but it's not recommended, as it's the only way to provide dictID in the frame header. 502 * @return : number of bytes written into dstBuffer. 503 * or an error code if it fails (can be tested using LZ4F_isError()) */ 504 LZ4FLIB_STATIC_API size_t LZ4F_compressFrame_usingCDict( 505 LZ4F_cctx* cctx, 506 void* dst, size_t dstCapacity, 507 const void* src, size_t srcSize, 508 const LZ4F_CDict* cdict, 509 const LZ4F_preferences_t* preferencesPtr); 510 511 512 /*! LZ4F_compressBegin_usingCDict() : 513 * Inits streaming dictionary compression, and writes the frame header into dstBuffer. 514 * dstCapacity must be >= LZ4F_HEADER_SIZE_MAX bytes. 515 * `prefsPtr` is optional : you may provide NULL as argument, 516 * however, it's the only way to provide dictID in the frame header. 517 * @return : number of bytes written into dstBuffer for the header, 518 * or an error code (which can be tested using LZ4F_isError()) */ 519 LZ4FLIB_STATIC_API size_t LZ4F_compressBegin_usingCDict( 520 LZ4F_cctx* cctx, 521 void* dstBuffer, size_t dstCapacity, 522 const LZ4F_CDict* cdict, 523 const LZ4F_preferences_t* prefsPtr); 524 525 526 /*! LZ4F_decompress_usingDict() : 527 * Same as LZ4F_decompress(), using a predefined dictionary. 528 * Dictionary is used "in place", without any preprocessing. 529 * It must remain accessible throughout the entire frame decoding. */ 530 LZ4FLIB_STATIC_API size_t LZ4F_decompress_usingDict( 531 LZ4F_dctx* dctxPtr, 532 void* dstBuffer, size_t* dstSizePtr, 533 const void* srcBuffer, size_t* srcSizePtr, 534 const void* dict, size_t dictSize, 535 const LZ4F_decompressOptions_t* decompressOptionsPtr); 536 537 #if defined (__cplusplus) 538 } 539 #endif 540 541 #endif /* defined(LZ4F_STATIC_LINKING_ONLY) && !defined(LZ4F_H_STATIC_09782039843) */ 542
