nlib
lz4frame.h
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.5.1.
37  * It also offers streaming capabilities.
38  * lz4.h is not required when using lz4frame.h.
39  * */
40 
41 #ifndef LZ4F_H_09782039843
42 #define LZ4F_H_09782039843
43 
44 #if defined (__cplusplus)
45 extern "C" {
46 #endif
47 
48 /* --- Dependency --- */
49 #include <stddef.h> /* size_t */
50 
51 
60 /*-***************************************************************
61  * Compiler specifics
62  *****************************************************************/
63 /* LZ4_DLL_EXPORT :
64  * Enable exporting of functions when building a Windows DLL
65  * LZ4FLIB_API :
66  * Control library symbols visibility.
67  */
68 #if defined(LZ4_DLL_EXPORT) && (LZ4_DLL_EXPORT==1)
69 # define LZ4FLIB_API __declspec(dllexport)
70 #elif defined(LZ4_DLL_IMPORT) && (LZ4_DLL_IMPORT==1)
71 # define LZ4FLIB_API __declspec(dllimport)
72 #elif defined(__GNUC__) && (__GNUC__ >= 4) && !defined(CAFE) && !defined(NN_PLATFORM_CTR)
73 # define LZ4FLIB_API __attribute__ ((__visibility__ ("default")))
74 #else
75 # define LZ4FLIB_API
76 #endif
77 
78 #ifdef LZ4F_DISABLE_DEPRECATE_WARNINGS
79 # define LZ4F_DEPRECATE(x) x
80 #else
81 # if defined(_MSC_VER)
82 # define LZ4F_DEPRECATE(x) x /* __declspec(deprecated) x - only works with C++ */
83 # elif defined(__clang__) || (defined(__GNUC__) && (__GNUC__ >= 6))
84 # define LZ4F_DEPRECATE(x) x __attribute__((deprecated))
85 # else
86 # define LZ4F_DEPRECATE(x) x /* no deprecation warning for this compiler */
87 # endif
88 #endif
89 
90 
91 /*-************************************
92  * Error management
93  **************************************/
94 typedef size_t LZ4F_errorCode_t;
95 
96 LZ4FLIB_API unsigned LZ4F_isError(LZ4F_errorCode_t code);
97 LZ4FLIB_API const char* LZ4F_getErrorName(LZ4F_errorCode_t code);
100 /*-************************************
101  * Frame compression types
102  **************************************/
103 /* #define LZ4F_ENABLE_OBSOLETE_ENUMS // uncomment to enable obsolete enums */
104 #ifdef LZ4F_ENABLE_OBSOLETE_ENUMS
105 # define LZ4F_OBSOLETE_ENUM(x) , LZ4F_DEPRECATE(x) = LZ4F_##x
106 #else
107 # define LZ4F_OBSOLETE_ENUM(x)
108 #endif
109 
110 /* The larger the block size, the (slightly) better the compression ratio,
111  * though there are diminishing returns.
112  * Larger blocks also increase memory usage on both compression and decompression sides. */
113 typedef enum {
114  LZ4F_default=0,
115  LZ4F_max64KB=4,
116  LZ4F_max256KB=5,
117  LZ4F_max1MB=6,
118  LZ4F_max4MB=7
119  LZ4F_OBSOLETE_ENUM(max64KB)
120  LZ4F_OBSOLETE_ENUM(max256KB)
121  LZ4F_OBSOLETE_ENUM(max1MB)
122  LZ4F_OBSOLETE_ENUM(max4MB)
123 } LZ4F_blockSizeID_t;
124 
125 /* Linked blocks sharply reduce inefficiencies when using small blocks,
126  * they compress better.
127  * However, some LZ4 decoders are only compatible with independent blocks */
128 typedef enum {
129  LZ4F_blockLinked=0,
130  LZ4F_blockIndependent
131  LZ4F_OBSOLETE_ENUM(blockLinked)
132  LZ4F_OBSOLETE_ENUM(blockIndependent)
133 } LZ4F_blockMode_t;
134 
135 typedef enum {
136  LZ4F_noContentChecksum=0,
137  LZ4F_contentChecksumEnabled
138  LZ4F_OBSOLETE_ENUM(noContentChecksum)
139  LZ4F_OBSOLETE_ENUM(contentChecksumEnabled)
140 } LZ4F_contentChecksum_t;
141 
142 typedef enum {
143  LZ4F_noBlockChecksum=0,
144  LZ4F_blockChecksumEnabled
145 } LZ4F_blockChecksum_t;
146 
147 typedef enum {
148  LZ4F_frame=0,
149  LZ4F_skippableFrame
150  LZ4F_OBSOLETE_ENUM(skippableFrame)
151 } LZ4F_frameType_t;
152 
153 #ifdef LZ4F_ENABLE_OBSOLETE_ENUMS
154 typedef LZ4F_blockSizeID_t blockSizeID_t;
155 typedef LZ4F_blockMode_t blockMode_t;
156 typedef LZ4F_frameType_t frameType_t;
157 typedef LZ4F_contentChecksum_t contentChecksum_t;
158 #endif
159 
164 typedef struct {
165  LZ4F_blockSizeID_t blockSizeID; /* max64KB, max256KB, max1MB, max4MB; 0 == default */
166  LZ4F_blockMode_t blockMode; /* LZ4F_blockLinked, LZ4F_blockIndependent; 0 == default */
167  LZ4F_contentChecksum_t contentChecksumFlag; /* 1: frame terminated with 32-bit checksum of decompressed data; 0: disabled (default) */
168  LZ4F_frameType_t frameType; /* read-only field : LZ4F_frame or LZ4F_skippableFrame */
169  unsigned long long contentSize; /* Size of uncompressed content ; 0 == unknown */
170  unsigned dictID; /* Dictionary ID, sent by compressor to help decoder select correct dictionary; 0 == no dictID provided */
171  LZ4F_blockChecksum_t blockChecksumFlag; /* 1: each block followed by a checksum of block's compressed data; 0: disabled (default) */
173 
178 typedef struct {
179  LZ4F_frameInfo_t frameInfo;
180  int compressionLevel; /* 0: default (fast mode); values > LZ4HC_CLEVEL_MAX count as LZ4HC_CLEVEL_MAX; values < 0 trigger "fast acceleration" */
181  unsigned autoFlush; /* 1: always flush, to reduce usage of internal buffers */
182  unsigned favorDecSpeed; /* 1: parser favors decompression speed vs compression ratio. Only works for high compression modes (>= LZ4LZ4HC_CLEVEL_OPT_MIN) */ /* >= v1.8.2 */
183  unsigned reserved[3]; /* must be zero for forward compatibility */
185 
186 LZ4FLIB_API int LZ4F_compressionLevel_max(void);
187 
188 
189 /*-*********************************
190 * Simple compression function
191 ***********************************/
198 LZ4FLIB_API size_t LZ4F_compressFrameBound(size_t srcSize, const LZ4F_preferences_t* preferencesPtr);
199 
207 LZ4FLIB_API size_t LZ4F_compressFrame(void* dstBuffer, size_t dstCapacity,
208  const void* srcBuffer, size_t srcSize,
209  const LZ4F_preferences_t* preferencesPtr);
210 
211 
212 /*-***********************************
213 * Advanced compression functions
214 *************************************/
215 typedef struct LZ4F_cctx_s LZ4F_cctx; /* incomplete type */
216 typedef LZ4F_cctx* LZ4F_compressionContext_t; /* for compatibility with previous API version */
217 
218 typedef struct {
219  unsigned stableSrc; /* 1 == src content will remain present on future calls to LZ4F_compress(); skip copying src content within tmp buffer */
220  unsigned reserved[3];
221 } LZ4F_compressOptions_t;
222 
223 /*--- Resource Management ---*/
224 
225 #define LZ4F_VERSION 100
226 LZ4FLIB_API unsigned LZ4F_getVersion(void);
235 LZ4FLIB_API LZ4F_errorCode_t LZ4F_createCompressionContext(LZ4F_cctx** cctxPtr, unsigned version);
236 LZ4FLIB_API LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx);
237 
238 
239 /*---- Compression ----*/
240 
241 #define LZ4F_HEADER_SIZE_MAX 19 /* LZ4 Frame header size can vary from 7 to 19 bytes */
242 
249 LZ4FLIB_API size_t LZ4F_compressBegin(LZ4F_cctx* cctx,
250  void* dstBuffer, size_t dstCapacity,
251  const LZ4F_preferences_t* prefsPtr);
252 
264 LZ4FLIB_API size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr);
265 
277 LZ4FLIB_API size_t LZ4F_compressUpdate(LZ4F_cctx* cctx,
278  void* dstBuffer, size_t dstCapacity,
279  const void* srcBuffer, size_t srcSize,
280  const LZ4F_compressOptions_t* cOptPtr);
281 
290 LZ4FLIB_API size_t LZ4F_flush(LZ4F_cctx* cctx,
291  void* dstBuffer, size_t dstCapacity,
292  const LZ4F_compressOptions_t* cOptPtr);
293 
303 LZ4FLIB_API size_t LZ4F_compressEnd(LZ4F_cctx* cctx,
304  void* dstBuffer, size_t dstCapacity,
305  const LZ4F_compressOptions_t* cOptPtr);
306 
307 
308 /*-*********************************
309 * Decompression functions
310 ***********************************/
311 typedef struct LZ4F_dctx_s LZ4F_dctx; /* incomplete type */
312 typedef LZ4F_dctx* LZ4F_decompressionContext_t; /* compatibility with previous API versions */
313 
314 typedef struct {
315  unsigned stableDst; /* pledges that last 64KB decompressed data will remain available unmodified. This optimization skips storage operations in tmp buffers. */
316  unsigned reserved[3]; /* must be set to zero for forward compatibility */
317 } LZ4F_decompressOptions_t;
318 
319 
320 /* Resource management */
321 
331 LZ4FLIB_API LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_dctx** dctxPtr, unsigned version);
332 LZ4FLIB_API LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx);
333 
334 
335 /*-***********************************
336 * Streaming decompression functions
337 *************************************/
338 
360 LZ4FLIB_API size_t LZ4F_getFrameInfo(LZ4F_dctx* dctx,
361  LZ4F_frameInfo_t* frameInfoPtr,
362  const void* srcBuffer, size_t* srcSizePtr);
363 
393 LZ4FLIB_API size_t LZ4F_decompress(LZ4F_dctx* dctx,
394  void* dstBuffer, size_t* dstSizePtr,
395  const void* srcBuffer, size_t* srcSizePtr,
396  const LZ4F_decompressOptions_t* dOptPtr);
397 
398 
404 LZ4FLIB_API void LZ4F_resetDecompressionContext(LZ4F_dctx* dctx); /* always successful */
405 
406 
407 
408 #if defined (__cplusplus)
409 }
410 #endif
411 
412 #endif /* LZ4F_H_09782039843 */
413 
414 #if defined(LZ4F_STATIC_LINKING_ONLY) && !defined(LZ4F_H_STATIC_09782039843)
415 #define LZ4F_H_STATIC_09782039843
416 
417 #if defined (__cplusplus)
418 extern "C" {
419 #endif
420 
421 /* These declarations are not stable and may change in the future. They are
422  * therefore only safe to depend on when the caller is statically linked
423  * against the library. To access their declarations, define
424  * LZ4F_STATIC_LINKING_ONLY.
425  *
426  * There is a further protection mechanism where these symbols aren't published
427  * into shared/dynamic libraries. You can override this behavior and force
428  * them to be published by defining LZ4F_PUBLISH_STATIC_FUNCTIONS. Use at
429  * your own risk.
430  */
431 #ifdef LZ4F_PUBLISH_STATIC_FUNCTIONS
432 #define LZ4FLIB_STATIC_API LZ4FLIB_API
433 #else
434 #define LZ4FLIB_STATIC_API
435 #endif
436 
437 
438 /* --- Error List --- */
439 #define LZ4F_LIST_ERRORS(ITEM) \
440  ITEM(OK_NoError) \
441  ITEM(ERROR_GENERIC) \
442  ITEM(ERROR_maxBlockSize_invalid) \
443  ITEM(ERROR_blockMode_invalid) \
444  ITEM(ERROR_contentChecksumFlag_invalid) \
445  ITEM(ERROR_compressionLevel_invalid) \
446  ITEM(ERROR_headerVersion_wrong) \
447  ITEM(ERROR_blockChecksum_invalid) \
448  ITEM(ERROR_reservedFlag_set) \
449  ITEM(ERROR_allocation_failed) \
450  ITEM(ERROR_srcSize_tooLarge) \
451  ITEM(ERROR_dstMaxSize_tooSmall) \
452  ITEM(ERROR_frameHeader_incomplete) \
453  ITEM(ERROR_frameType_unknown) \
454  ITEM(ERROR_frameSize_wrong) \
455  ITEM(ERROR_srcPtr_wrong) \
456  ITEM(ERROR_decompressionFailed) \
457  ITEM(ERROR_headerChecksum_invalid) \
458  ITEM(ERROR_contentChecksum_invalid) \
459  ITEM(ERROR_frameDecoding_alreadyStarted) \
460  ITEM(ERROR_maxCode)
461 
462 #define LZ4F_GENERATE_ENUM(ENUM) LZ4F_##ENUM,
463 
464 /* enum list is exposed, to handle specific errors */
465 typedef enum { LZ4F_LIST_ERRORS(LZ4F_GENERATE_ENUM) } LZ4F_errorCodes;
466 
467 LZ4FLIB_STATIC_API LZ4F_errorCodes LZ4F_getErrorCode(size_t functionResult);
468 
469 
470 
471 /**********************************
472  * Bulk processing dictionary API
473  *********************************/
474 typedef struct LZ4F_CDict_s LZ4F_CDict;
475 
481 LZ4FLIB_STATIC_API LZ4F_CDict* LZ4F_createCDict(const void* dictBuffer, size_t dictSize);
482 LZ4FLIB_STATIC_API void LZ4F_freeCDict(LZ4F_CDict* CDict);
483 
484 
495 LZ4FLIB_STATIC_API size_t LZ4F_compressFrame_usingCDict(
496  LZ4F_cctx* cctx,
497  void* dst, size_t dstCapacity,
498  const void* src, size_t srcSize,
499  const LZ4F_CDict* cdict,
500  const LZ4F_preferences_t* preferencesPtr);
501 
502 
510 LZ4FLIB_STATIC_API size_t LZ4F_compressBegin_usingCDict(
511  LZ4F_cctx* cctx,
512  void* dstBuffer, size_t dstCapacity,
513  const LZ4F_CDict* cdict,
514  const LZ4F_preferences_t* prefsPtr);
515 
516 
521 LZ4FLIB_STATIC_API size_t LZ4F_decompress_usingDict(
522  LZ4F_dctx* dctxPtr,
523  void* dstBuffer, size_t* dstSizePtr,
524  const void* srcBuffer, size_t* srcSizePtr,
525  const void* dict, size_t dictSize,
526  const LZ4F_decompressOptions_t* decompressOptionsPtr);
527 
528 #if defined (__cplusplus)
529 }
530 #endif
531 
532 #endif /* defined(LZ4F_STATIC_LINKING_ONLY) && !defined(LZ4F_H_STATIC_09782039843) */