1 /*
2    LZ4 auto-framing library
3    Header File
4    Copyright (C) 2011-2020, 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 able to create and decode LZ4 frames
36  * conformant with specification v1.6.1 in doc/lz4_Frame_format.md .
37  * Generated frames are compatible with `lz4` CLI.
38  *
39  * LZ4F also offers streaming capabilities.
40  *
41  * lz4.h is not required when using lz4frame.h,
42  * except to extract common constant such as LZ4_VERSION_NUMBER.
43  * */
44 
45 #ifndef LZ4F_H_09782039843
46 #define LZ4F_H_09782039843
47 
48 #if defined (__cplusplus)
49 extern "C" {
50 #endif
51 
52 /* ---   Dependency   --- */
53 #include <stddef.h>   /* size_t */
54 
55 
56 /**
57   Introduction
58 
59   lz4frame.h implements LZ4 frame specification (doc/lz4_Frame_format.md).
60   lz4frame.h provides frame compression functions that take care
61   of encoding standard metadata alongside LZ4-compressed blocks.
62 */
63 
64 /*-***************************************************************
65  *  Compiler specifics
66  *****************************************************************/
67 /*  LZ4_DLL_EXPORT :
68  *  Enable exporting of functions when building a Windows DLL
69  *  LZ4FLIB_VISIBILITY :
70  *  Control library symbols visibility.
71  */
72 #ifndef LZ4FLIB_VISIBILITY
73 #  if defined(__GNUC__) && (__GNUC__ >= 4)
74 #    define LZ4FLIB_VISIBILITY __attribute__ ((visibility ("default")))
75 #  else
76 #    define LZ4FLIB_VISIBILITY
77 #  endif
78 #endif
79 #if defined(LZ4_DLL_EXPORT) && (LZ4_DLL_EXPORT==1)
80 #  define LZ4FLIB_API __declspec(dllexport) LZ4FLIB_VISIBILITY
81 #elif defined(LZ4_DLL_IMPORT) && (LZ4_DLL_IMPORT==1)
82 #  define LZ4FLIB_API __declspec(dllimport) LZ4FLIB_VISIBILITY
83 #else
84 #  define LZ4FLIB_API LZ4FLIB_VISIBILITY
85 #endif
86 
87 #ifdef LZ4F_DISABLE_DEPRECATE_WARNINGS
88 #  define LZ4F_DEPRECATE(x) x
89 #else
90 #  if defined(_MSC_VER)
91 #    define LZ4F_DEPRECATE(x) x   /* __declspec(deprecated) x - only works with C++ */
92 #  elif defined(__clang__) || (defined(__GNUC__) && (__GNUC__ >= 6))
93 #    define LZ4F_DEPRECATE(x) x __attribute__((deprecated))
94 #  else
95 #    define LZ4F_DEPRECATE(x) x   /* no deprecation warning for this compiler */
96 #  endif
97 #endif
98 
99 
100 /*-************************************
101  *  Error management
102  **************************************/
103 typedef size_t LZ4F_errorCode_t;
104 
105 LZ4FLIB_API unsigned    LZ4F_isError(LZ4F_errorCode_t code);   /**< tells when a function result is an error code */
106 LZ4FLIB_API const char* LZ4F_getErrorName(LZ4F_errorCode_t code);   /**< return error code string; for debugging */
107 
108 
109 /*-************************************
110  *  Frame compression types
111  ************************************* */
112 /* #define LZ4F_ENABLE_OBSOLETE_ENUMS   // uncomment to enable obsolete enums */
113 #ifdef LZ4F_ENABLE_OBSOLETE_ENUMS
114 #  define LZ4F_OBSOLETE_ENUM(x) , LZ4F_DEPRECATE(x) = LZ4F_##x
115 #else
116 #  define LZ4F_OBSOLETE_ENUM(x)
117 #endif
118 
119 /* The larger the block size, the (slightly) better the compression ratio,
120  * though there are diminishing returns.
121  * Larger blocks also increase memory usage on both compression and decompression sides.
122  */
123 typedef enum {
124     LZ4F_default=0,
125     LZ4F_max64KB=4,
126     LZ4F_max256KB=5,
127     LZ4F_max1MB=6,
128     LZ4F_max4MB=7
129     LZ4F_OBSOLETE_ENUM(max64KB)
130     LZ4F_OBSOLETE_ENUM(max256KB)
131     LZ4F_OBSOLETE_ENUM(max1MB)
132     LZ4F_OBSOLETE_ENUM(max4MB)
133 } LZ4F_blockSizeID_t;
134 
135 /* Linked blocks sharply reduce inefficiencies when using small blocks,
136  * they compress better.
137  * However, some LZ4 decoders are only compatible with independent blocks */
138 typedef enum {
139     LZ4F_blockLinked=0,
140     LZ4F_blockIndependent
141     LZ4F_OBSOLETE_ENUM(blockLinked)
142     LZ4F_OBSOLETE_ENUM(blockIndependent)
143 } LZ4F_blockMode_t;
144 
145 typedef enum {
146     LZ4F_noContentChecksum=0,
147     LZ4F_contentChecksumEnabled
148     LZ4F_OBSOLETE_ENUM(noContentChecksum)
149     LZ4F_OBSOLETE_ENUM(contentChecksumEnabled)
150 } LZ4F_contentChecksum_t;
151 
152 typedef enum {
153     LZ4F_noBlockChecksum=0,
154     LZ4F_blockChecksumEnabled
155 } LZ4F_blockChecksum_t;
156 
157 typedef enum {
158     LZ4F_frame=0,
159     LZ4F_skippableFrame
160     LZ4F_OBSOLETE_ENUM(skippableFrame)
161 } LZ4F_frameType_t;
162 
163 #ifdef LZ4F_ENABLE_OBSOLETE_ENUMS
164 typedef LZ4F_blockSizeID_t blockSizeID_t;
165 typedef LZ4F_blockMode_t blockMode_t;
166 typedef LZ4F_frameType_t frameType_t;
167 typedef LZ4F_contentChecksum_t contentChecksum_t;
168 #endif
169 
170 /*! LZ4F_frameInfo_t :
171  *  makes it possible to set or read frame parameters.
172  *  Structure must be first init to 0, using memset() or LZ4F_INIT_FRAMEINFO,
173  *  setting all parameters to default.
174  *  It's then possible to update selectively some parameters */
175 typedef struct {
176   LZ4F_blockSizeID_t     blockSizeID;         /* max64KB, max256KB, max1MB, max4MB; 0 == default */
177   LZ4F_blockMode_t       blockMode;           /* LZ4F_blockLinked, LZ4F_blockIndependent; 0 == default */
178   LZ4F_contentChecksum_t contentChecksumFlag; /* 1: frame terminated with 32-bit checksum of decompressed data; 0: disabled (default) */
179   LZ4F_frameType_t       frameType;           /* read-only field : LZ4F_frame or LZ4F_skippableFrame */
180   unsigned long long     contentSize;         /* Size of uncompressed content ; 0 == unknown */
181   unsigned               dictID;              /* Dictionary ID, sent by compressor to help decoder select correct dictionary; 0 == no dictID provided */
182   LZ4F_blockChecksum_t   blockChecksumFlag;   /* 1: each block followed by a checksum of block's compressed data; 0: disabled (default) */
183 } LZ4F_frameInfo_t;
184 
185 #define LZ4F_INIT_FRAMEINFO   { LZ4F_default, LZ4F_blockLinked, LZ4F_noContentChecksum, LZ4F_frame, 0ULL, 0U, LZ4F_noBlockChecksum }    /* v1.8.3+ */
186 
187 /*! LZ4F_preferences_t :
188  *  makes it possible to supply advanced compression instructions to streaming interface.
189  *  Structure must be first init to 0, using memset() or LZ4F_INIT_PREFERENCES,
190  *  setting all parameters to default.
191  *  All reserved fields must be set to zero. */
192 typedef struct {
193   LZ4F_frameInfo_t frameInfo;
194   int      compressionLevel;    /* 0: default (fast mode); values > LZ4HC_CLEVEL_MAX count as LZ4HC_CLEVEL_MAX; values < 0 trigger "fast acceleration" */
195   unsigned autoFlush;           /* 1: always flush; reduces usage of internal buffers */
196   unsigned favorDecSpeed;       /* 1: parser favors decompression speed vs compression ratio. Only works for high compression modes (>= LZ4HC_CLEVEL_OPT_MIN) */  /* v1.8.2+ */
197   unsigned reserved[3];         /* must be zero for forward compatibility */
198 } LZ4F_preferences_t;
199 
200 #define LZ4F_INIT_PREFERENCES   { LZ4F_INIT_FRAMEINFO, 0, 0u, 0u, { 0u, 0u, 0u } }    /* v1.8.3+ */
201 
202 
203 /*-*********************************
204 *  Simple compression function
205 ***********************************/
206 
207 LZ4FLIB_API int LZ4F_compressionLevel_max(void);   /* v1.8.0+ */
208 
209 /*! LZ4F_compressFrameBound() :
210  *  Returns the maximum possible compressed size with LZ4F_compressFrame() given srcSize and preferences.
211  * `preferencesPtr` is optional. It can be replaced by NULL, in which case, the function will assume default preferences.
212  *  Note : this result is only usable with LZ4F_compressFrame().
213  *         It may also be used with LZ4F_compressUpdate() _if no flush() operation_ is performed.
214  */
215 LZ4FLIB_API size_t LZ4F_compressFrameBound(size_t srcSize, const LZ4F_preferences_t* preferencesPtr);
216 
217 /*! LZ4F_compressFrame() :
218  *  Compress an entire srcBuffer into a valid LZ4 frame.
219  *  dstCapacity MUST be >= LZ4F_compressFrameBound(srcSize, preferencesPtr).
220  *  The LZ4F_preferences_t structure is optional : you can provide NULL as argument. All preferences will be set to default.
221  * @return : number of bytes written into dstBuffer.
222  *           or an error code if it fails (can be tested using LZ4F_isError())
223  */
224 LZ4FLIB_API size_t LZ4F_compressFrame(void* dstBuffer, size_t dstCapacity,
225                                 const void* srcBuffer, size_t srcSize,
226                                 const LZ4F_preferences_t* preferencesPtr);
227 
228 
229 /*-***********************************
230 *  Advanced compression functions
231 *************************************/
232 typedef struct LZ4F_cctx_s LZ4F_cctx;   /* incomplete type */
233 typedef LZ4F_cctx* LZ4F_compressionContext_t;   /* for compatibility with previous API version */
234 
235 typedef struct {
236   unsigned stableSrc;    /* 1 == src content will remain present on future calls to LZ4F_compress(); skip copying src content within tmp buffer */
237   unsigned reserved[3];
238 } LZ4F_compressOptions_t;
239 
240 /*---   Resource Management   ---*/
241 
242 #define LZ4F_VERSION 100    /* This number can be used to check for an incompatible API breaking change */
243 LZ4FLIB_API unsigned LZ4F_getVersion(void);
244 
245 /*! LZ4F_createCompressionContext() :
246  * The first thing to do is to create a compressionContext object, which will be used in all compression operations.
247  * This is achieved using LZ4F_createCompressionContext(), which takes as argument a version.
248  * The version provided MUST be LZ4F_VERSION. It is intended to track potential version mismatch, notably when using DLL.
249  * The function will provide a pointer to a fully allocated LZ4F_cctx object.
250  * If @return != zero, there was an error during context creation.
251  * Object can release its memory using LZ4F_freeCompressionContext();
252  */
253 LZ4FLIB_API LZ4F_errorCode_t LZ4F_createCompressionContext(LZ4F_cctx** cctxPtr, unsigned version);
254 LZ4FLIB_API LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx);
255 
256 
257 /*----    Compression    ----*/
258 
259 #define LZ4F_HEADER_SIZE_MIN  7   /* LZ4 Frame header size can vary, depending on selected paramaters */
260 #define LZ4F_HEADER_SIZE_MAX 19
261 
262 /* Size in bytes of a block header in little-endian format. Highest bit indicates if block data is uncompressed */
263 #define LZ4F_BLOCK_HEADER_SIZE 4
264 
265 /* Size in bytes of a block checksum footer in little-endian format. */
266 #define LZ4F_BLOCK_CHECKSUM_SIZE 4
267 
268 /* Size in bytes of the content checksum. */
269 #define LZ4F_CONTENT_CHECKSUM_SIZE 4
270 
271 /*! LZ4F_compressBegin() :
272  *  will write the frame header into dstBuffer.
273  *  dstCapacity must be >= LZ4F_HEADER_SIZE_MAX bytes.
274  * `prefsPtr` is optional : you can provide NULL as argument, all preferences will then be set to default.
275  * @return : number of bytes written into dstBuffer for the header
276  *           or an error code (which can be tested using LZ4F_isError())
277  */
278 LZ4FLIB_API size_t LZ4F_compressBegin(LZ4F_cctx* cctx,
279                                       void* dstBuffer, size_t dstCapacity,
280                                       const LZ4F_preferences_t* prefsPtr);
281 
282 /*! LZ4F_compressBound() :
283  *  Provides minimum dstCapacity required to guarantee success of
284  *  LZ4F_compressUpdate(), given a srcSize and preferences, for a worst case scenario.
285  *  When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() instead.
286  *  Note that the result is only valid for a single invocation of LZ4F_compressUpdate().
287  *  When invoking LZ4F_compressUpdate() multiple times,
288  *  if the output buffer is gradually filled up instead of emptied and re-used from its start,
289  *  one must check if there is enough remaining capacity before each invocation, using LZ4F_compressBound().
290  * @return is always the same for a srcSize and prefsPtr.
291  *  prefsPtr is optional : when NULL is provided, preferences will be set to cover worst case scenario.
292  *  tech details :
293  * @return if automatic flushing is not enabled, includes the possibility that internal buffer might already be filled by up to (blockSize-1) bytes.
294  *  It also includes frame footer (ending + checksum), since it might be generated by LZ4F_compressEnd().
295  * @return doesn't include frame header, as it was already generated by LZ4F_compressBegin().
296  */
297 LZ4FLIB_API size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr);
298 
299 /*! LZ4F_compressUpdate() :
300  *  LZ4F_compressUpdate() can be called repetitively to compress as much data as necessary.
301  *  Important rule: dstCapacity MUST be large enough to ensure operation success even in worst case situations.
302  *  This value is provided by LZ4F_compressBound().
303  *  If this condition is not respected, LZ4F_compress() will fail (result is an errorCode).
304  *  LZ4F_compressUpdate() doesn't guarantee error recovery.
305  *  When an error occurs, compression context must be freed or resized.
306  * `cOptPtr` is optional : NULL can be provided, in which case all options are set to default.
307  * @return : number of bytes written into `dstBuffer` (it can be zero, meaning input data was just buffered).
308  *           or an error code if it fails (which can be tested using LZ4F_isError())
309  */
310 LZ4FLIB_API size_t LZ4F_compressUpdate(LZ4F_cctx* cctx,
311                                        void* dstBuffer, size_t dstCapacity,
312                                  const void* srcBuffer, size_t srcSize,
313                                  const LZ4F_compressOptions_t* cOptPtr);
314 
315 /*! LZ4F_flush() :
316  *  When data must be generated and sent immediately, without waiting for a block to be completely filled,
317  *  it's possible to call LZ4_flush(). It will immediately compress any data buffered within cctx.
318  * `dstCapacity` must be large enough to ensure the operation will be successful.
319  * `cOptPtr` is optional : it's possible to provide NULL, all options will be set to default.
320  * @return : nb of bytes written into dstBuffer (can be zero, when there is no data stored within cctx)
321  *           or an error code if it fails (which can be tested using LZ4F_isError())
322  *  Note : LZ4F_flush() is guaranteed to be successful when dstCapacity >= LZ4F_compressBound(0, prefsPtr).
323  */
324 LZ4FLIB_API size_t LZ4F_flush(LZ4F_cctx* cctx,
325                               void* dstBuffer, size_t dstCapacity,
326                         const LZ4F_compressOptions_t* cOptPtr);
327 
328 /*! LZ4F_compressEnd() :
329  *  To properly finish an LZ4 frame, invoke LZ4F_compressEnd().
330  *  It will flush whatever data remained within `cctx` (like LZ4_flush())
331  *  and properly finalize the frame, with an endMark and a checksum.
332  * `cOptPtr` is optional : NULL can be provided, in which case all options will be set to default.
333  * @return : nb of bytes written into dstBuffer, necessarily >= 4 (endMark),
334  *           or an error code if it fails (which can be tested using LZ4F_isError())
335  *  Note : LZ4F_compressEnd() is guaranteed to be successful when dstCapacity >= LZ4F_compressBound(0, prefsPtr).
336  *  A successful call to LZ4F_compressEnd() makes `cctx` available again for another compression task.
337  */
338 LZ4FLIB_API size_t LZ4F_compressEnd(LZ4F_cctx* cctx,
339                                     void* dstBuffer, size_t dstCapacity,
340                               const LZ4F_compressOptions_t* cOptPtr);
341 
342 
343 /*-*********************************
344 *  Decompression functions
345 ***********************************/
346 typedef struct LZ4F_dctx_s LZ4F_dctx;   /* incomplete type */
347 typedef LZ4F_dctx* LZ4F_decompressionContext_t;   /* compatibility with previous API versions */
348 
349 typedef struct {
350   unsigned stableDst;    /* pledges that last 64KB decompressed data will remain available unmodified. This optimization skips storage operations in tmp buffers. */
351   unsigned reserved[3];  /* must be set to zero for forward compatibility */
352 } LZ4F_decompressOptions_t;
353 
354 
355 /* Resource management */
356 
357 /*! LZ4F_createDecompressionContext() :
358  *  Create an LZ4F_dctx object, to track all decompression operations.
359  *  The version provided MUST be LZ4F_VERSION.
360  *  The function provides a pointer to an allocated and initialized LZ4F_dctx object.
361  *  The result is an errorCode, which can be tested using LZ4F_isError().
362  *  dctx memory can be released using LZ4F_freeDecompressionContext();
363  *  Result of LZ4F_freeDecompressionContext() indicates current state of decompressionContext when being released.
364  *  That is, it should be == 0 if decompression has been completed fully and correctly.
365  */
366 LZ4FLIB_API LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_dctx** dctxPtr, unsigned version);
367 LZ4FLIB_API LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx);
368 
369 
370 /*-***********************************
371 *  Streaming decompression functions
372 *************************************/
373 
374 #define LZ4F_MIN_SIZE_TO_KNOW_HEADER_LENGTH 5
375 
376 /*! LZ4F_headerSize() : v1.9.0+
377  *  Provide the header size of a frame starting at `src`.
378  * `srcSize` must be >= LZ4F_MIN_SIZE_TO_KNOW_HEADER_LENGTH,
379  *  which is enough to decode the header length.
380  * @return : size of frame header
381  *           or an error code, which can be tested using LZ4F_isError()
382  *  note : Frame header size is variable, but is guaranteed to be
383  *         >= LZ4F_HEADER_SIZE_MIN bytes, and <= LZ4F_HEADER_SIZE_MAX bytes.
384  */
385 LZ4FLIB_API size_t LZ4F_headerSize(const void* src, size_t srcSize);
386 
387 /*! LZ4F_getFrameInfo() :
388  *  This function extracts frame parameters (max blockSize, dictID, etc.).
389  *  Its usage is optional: user can call LZ4F_decompress() directly.
390  *
391  *  Extracted information will fill an existing LZ4F_frameInfo_t structure.
392  *  This can be useful for allocation and dictionary identification purposes.
393  *
394  *  LZ4F_getFrameInfo() can work in the following situations :
395  *
396  *  1) At the beginning of a new frame, before any invocation of LZ4F_decompress().
397  *     It will decode header from `srcBuffer`,
398  *     consuming the header and starting the decoding process.
399  *
400  *     Input size must be large enough to contain the full frame header.
401  *     Frame header size can be known beforehand by LZ4F_headerSize().
402  *     Frame header size is variable, but is guaranteed to be >= LZ4F_HEADER_SIZE_MIN bytes,
403  *     and not more than <= LZ4F_HEADER_SIZE_MAX bytes.
404  *     Hence, blindly providing LZ4F_HEADER_SIZE_MAX bytes or more will always work.
405  *     It's allowed to provide more input data than the header size,
406  *     LZ4F_getFrameInfo() will only consume the header.
407  *
408  *     If input size is not large enough,
409  *     aka if it's smaller than header size,
410  *     function will fail and return an error code.
411  *
412  *  2) After decoding has been started,
413  *     it's possible to invoke LZ4F_getFrameInfo() anytime
414  *     to extract already decoded frame parameters stored within dctx.
415  *
416  *     Note that, if decoding has barely started,
417  *     and not yet read enough information to decode the header,
418  *     LZ4F_getFrameInfo() will fail.
419  *
420  *  The number of bytes consumed from srcBuffer will be updated in *srcSizePtr (necessarily <= original value).
421  *  LZ4F_getFrameInfo() only consumes bytes when decoding has not yet started,
422  *  and when decoding the header has been successful.
423  *  Decompression must then resume from (srcBuffer + *srcSizePtr).
424  *
425  * @return : a hint about how many srcSize bytes LZ4F_decompress() expects for next call,
426  *           or an error code which can be tested using LZ4F_isError().
427  *  note 1 : in case of error, dctx is not modified. Decoding operation can resume from beginning safely.
428  *  note 2 : frame parameters are *copied into* an already allocated LZ4F_frameInfo_t structure.
429  */
430 LZ4FLIB_API size_t LZ4F_getFrameInfo(LZ4F_dctx* dctx,
431                                      LZ4F_frameInfo_t* frameInfoPtr,
432                                      const void* srcBuffer, size_t* srcSizePtr);
433 
434 /*! LZ4F_decompress() :
435  *  Call this function repetitively to regenerate data compressed in `srcBuffer`.
436  *
437  *  The function requires a valid dctx state.
438  *  It will read up to *srcSizePtr bytes from srcBuffer,
439  *  and decompress data into dstBuffer, of capacity *dstSizePtr.
440  *
441  *  The nb of bytes consumed from srcBuffer will be written into *srcSizePtr (necessarily <= original value).
442  *  The nb of bytes decompressed into dstBuffer will be written into *dstSizePtr (necessarily <= original value).
443  *
444  *  The function does not necessarily read all input bytes, so always check value in *srcSizePtr.
445  *  Unconsumed source data must be presented again in subsequent invocations.
446  *
447  * `dstBuffer` can freely change between each consecutive function invocation.
448  * `dstBuffer` content will be overwritten.
449  *
450  * @return : an hint of how many `srcSize` bytes LZ4F_decompress() expects for next call.
451  *  Schematically, it's the size of the current (or remaining) compressed block + header of next block.
452  *  Respecting the hint provides some small speed benefit, because it skips intermediate buffers.
453  *  This is just a hint though, it's always possible to provide any srcSize.
454  *
455  *  When a frame is fully decoded, @return will be 0 (no more data expected).
456  *  When provided with more bytes than necessary to decode a frame,
457  *  LZ4F_decompress() will stop reading exactly at end of current frame, and @return 0.
458  *
459  *  If decompression failed, @return is an error code, which can be tested using LZ4F_isError().
460  *  After a decompression error, the `dctx` context is not resumable.
461  *  Use LZ4F_resetDecompressionContext() to return to clean state.
462  *
463  *  After a frame is fully decoded, dctx can be used again to decompress another frame.
464  */
465 LZ4FLIB_API size_t LZ4F_decompress(LZ4F_dctx* dctx,
466                                    void* dstBuffer, size_t* dstSizePtr,
467                                    const void* srcBuffer, size_t* srcSizePtr,
468                                    const LZ4F_decompressOptions_t* dOptPtr);
469 
470 
471 /*! LZ4F_resetDecompressionContext() : added in v1.8.0
472  *  In case of an error, the context is left in "undefined" state.
473  *  In which case, it's necessary to reset it, before re-using it.
474  *  This method can also be used to abruptly stop any unfinished decompression,
475  *  and start a new one using same context resources. */
476 LZ4FLIB_API void LZ4F_resetDecompressionContext(LZ4F_dctx* dctx);   /* always successful */
477 
478 
479 
480 #if defined (__cplusplus)
481 }
482 #endif
483 
484 #endif  /* LZ4F_H_09782039843 */
485 
486 #if defined(LZ4F_STATIC_LINKING_ONLY) && !defined(LZ4F_H_STATIC_09782039843)
487 #define LZ4F_H_STATIC_09782039843
488 
489 #if defined (__cplusplus)
490 extern "C" {
491 #endif
492 
493 /* These declarations are not stable and may change in the future.
494  * They are therefore only safe to depend on
495  * when the caller is statically linked against the library.
496  * To access their declarations, define LZ4F_STATIC_LINKING_ONLY.
497  *
498  * By default, these symbols aren't published into shared/dynamic libraries.
499  * You can override this behavior and force them to be published
500  * by defining LZ4F_PUBLISH_STATIC_FUNCTIONS.
501  * Use at your own risk.
502  */
503 #ifdef LZ4F_PUBLISH_STATIC_FUNCTIONS
504 # define LZ4FLIB_STATIC_API LZ4FLIB_API
505 #else
506 # define LZ4FLIB_STATIC_API
507 #endif
508 
509 
510 /* ---   Error List   --- */
511 #define LZ4F_LIST_ERRORS(ITEM) \
512         ITEM(OK_NoError) \
513         ITEM(ERROR_GENERIC) \
514         ITEM(ERROR_maxBlockSize_invalid) \
515         ITEM(ERROR_blockMode_invalid) \
516         ITEM(ERROR_contentChecksumFlag_invalid) \
517         ITEM(ERROR_compressionLevel_invalid) \
518         ITEM(ERROR_headerVersion_wrong) \
519         ITEM(ERROR_blockChecksum_invalid) \
520         ITEM(ERROR_reservedFlag_set) \
521         ITEM(ERROR_allocation_failed) \
522         ITEM(ERROR_srcSize_tooLarge) \
523         ITEM(ERROR_dstMaxSize_tooSmall) \
524         ITEM(ERROR_frameHeader_incomplete) \
525         ITEM(ERROR_frameType_unknown) \
526         ITEM(ERROR_frameSize_wrong) \
527         ITEM(ERROR_srcPtr_wrong) \
528         ITEM(ERROR_decompressionFailed) \
529         ITEM(ERROR_headerChecksum_invalid) \
530         ITEM(ERROR_contentChecksum_invalid) \
531         ITEM(ERROR_frameDecoding_alreadyStarted) \
532         ITEM(ERROR_maxCode)
533 
534 #define LZ4F_GENERATE_ENUM(ENUM) LZ4F_##ENUM,
535 
536 /* enum list is exposed, to handle specific errors */
537 typedef enum { LZ4F_LIST_ERRORS(LZ4F_GENERATE_ENUM)
538               _LZ4F_dummy_error_enum_for_c89_never_used } LZ4F_errorCodes;
539 
540 LZ4FLIB_STATIC_API LZ4F_errorCodes LZ4F_getErrorCode(size_t functionResult);
541 
542 LZ4FLIB_STATIC_API size_t LZ4F_getBlockSize(unsigned);
543 
544 /**********************************
545  *  Bulk processing dictionary API
546  *********************************/
547 
548 /* A Dictionary is useful for the compression of small messages (KB range).
549  * It dramatically improves compression efficiency.
550  *
551  * LZ4 can ingest any input as dictionary, though only the last 64 KB are useful.
552  * Best results are generally achieved by using Zstandard's Dictionary Builder
553  * to generate a high-quality dictionary from a set of samples.
554  *
555  * Loading a dictionary has a cost, since it involves construction of tables.
556  * The Bulk processing dictionary API makes it possible to share this cost
557  * over an arbitrary number of compression jobs, even concurrently,
558  * markedly improving compression latency for these cases.
559  *
560  * The same dictionary will have to be used on the decompression side
561  * for decoding to be successful.
562  * To help identify the correct dictionary at decoding stage,
563  * the frame header allows optional embedding of a dictID field.
564  */
565 typedef struct LZ4F_CDict_s LZ4F_CDict;
566 
567 /*! LZ4_createCDict() :
568  *  When compressing multiple messages / blocks using the same dictionary, it's recommended to load it just once.
569  *  LZ4_createCDict() will create a digested dictionary, ready to start future compression operations without startup delay.
570  *  LZ4_CDict can be created once and shared by multiple threads concurrently, since its usage is read-only.
571  * `dictBuffer` can be released after LZ4_CDict creation, since its content is copied within CDict */
572 LZ4FLIB_STATIC_API LZ4F_CDict* LZ4F_createCDict(const void* dictBuffer, size_t dictSize);
573 LZ4FLIB_STATIC_API void        LZ4F_freeCDict(LZ4F_CDict* CDict);
574 
575 
576 /*! LZ4_compressFrame_usingCDict() :
577  *  Compress an entire srcBuffer into a valid LZ4 frame using a digested Dictionary.
578  *  cctx must point to a context created by LZ4F_createCompressionContext().
579  *  If cdict==NULL, compress without a dictionary.
580  *  dstBuffer MUST be >= LZ4F_compressFrameBound(srcSize, preferencesPtr).
581  *  If this condition is not respected, function will fail (@return an errorCode).
582  *  The LZ4F_preferences_t structure is optional : you may provide NULL as argument,
583  *  but it's not recommended, as it's the only way to provide dictID in the frame header.
584  * @return : number of bytes written into dstBuffer.
585  *           or an error code if it fails (can be tested using LZ4F_isError()) */
586 LZ4FLIB_STATIC_API size_t LZ4F_compressFrame_usingCDict(
587     LZ4F_cctx* cctx,
588     void* dst, size_t dstCapacity,
589     const void* src, size_t srcSize,
590     const LZ4F_CDict* cdict,
591     const LZ4F_preferences_t* preferencesPtr);
592 
593 
594 /*! LZ4F_compressBegin_usingCDict() :
595  *  Inits streaming dictionary compression, and writes the frame header into dstBuffer.
596  *  dstCapacity must be >= LZ4F_HEADER_SIZE_MAX bytes.
597  * `prefsPtr` is optional : you may provide NULL as argument,
598  *  however, it's the only way to provide dictID in the frame header.
599  * @return : number of bytes written into dstBuffer for the header,
600  *           or an error code (which can be tested using LZ4F_isError()) */
601 LZ4FLIB_STATIC_API size_t LZ4F_compressBegin_usingCDict(
602     LZ4F_cctx* cctx,
603     void* dstBuffer, size_t dstCapacity,
604     const LZ4F_CDict* cdict,
605     const LZ4F_preferences_t* prefsPtr);
606 
607 
608 /*! LZ4F_decompress_usingDict() :
609  *  Same as LZ4F_decompress(), using a predefined dictionary.
610  *  Dictionary is used "in place", without any preprocessing.
611  *  It must remain accessible throughout the entire frame decoding. */
612 LZ4FLIB_STATIC_API size_t LZ4F_decompress_usingDict(
613     LZ4F_dctx* dctxPtr,
614     void* dstBuffer, size_t* dstSizePtr,
615     const void* srcBuffer, size_t* srcSizePtr,
616     const void* dict, size_t dictSize,
617     const LZ4F_decompressOptions_t* decompressOptionsPtr);
618 
619 #if defined (__cplusplus)
620 }
621 #endif
622 
623 #endif  /* defined(LZ4F_STATIC_LINKING_ONLY) && !defined(LZ4F_H_STATIC_09782039843) */
624