source: thirdparty/blosc/internal-complibs/zstd-0.7.4/common/zstd.h @ 8ebc79b

Revision 8ebc79b, 23.9 KB checked in by Hal Finkel <hfinkel@…>, 8 years ago (diff)

Add the other internal compression libraries from blocs

  • Property mode set to 100644
Line 
1/*
2    zstd - standard compression library
3    Header File
4    Copyright (C) 2014-2016, Yann Collet.
5
6    BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php)
7
8    Redistribution and use in source and binary forms, with or without
9    modification, are permitted provided that the following conditions are
10    met:
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    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
19    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
20    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
21    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
22    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
23    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
24    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
25    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
27    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28
29    You can contact the author at :
30    - zstd source repository : https://github.com/Cyan4973/zstd
31*/
32#ifndef ZSTD_H_235446
33#define ZSTD_H_235446
34
35#if defined (__cplusplus)
36extern "C" {
37#endif
38
39/*-*************************************
40*  Dependencies
41***************************************/
42#include <stddef.h>   /* size_t */
43
44
45/*-***************************************************************
46*  Export parameters
47*****************************************************************/
48/*!
49*  ZSTD_DLL_EXPORT :
50*  Enable exporting of functions when building a Windows DLL
51*/
52#if defined(_WIN32) && defined(ZSTD_DLL_EXPORT) && (ZSTD_DLL_EXPORT==1)
53#  define ZSTDLIB_API __declspec(dllexport)
54#else
55#  define ZSTDLIB_API
56#endif
57
58
59/* *************************************
60*  Version
61***************************************/
62#define ZSTD_VERSION_MAJOR    0
63#define ZSTD_VERSION_MINOR    7
64#define ZSTD_VERSION_RELEASE  4
65
66#define ZSTD_LIB_VERSION ZSTD_VERSION_MAJOR.ZSTD_VERSION_MINOR.ZSTD_VERSION_RELEASE
67#define ZSTD_QUOTE(str) #str
68#define ZSTD_EXPAND_AND_QUOTE(str) ZSTD_QUOTE(str)
69#define ZSTD_VERSION_STRING ZSTD_EXPAND_AND_QUOTE(ZSTD_LIB_VERSION)
70
71#define ZSTD_VERSION_NUMBER  (ZSTD_VERSION_MAJOR *100*100 + ZSTD_VERSION_MINOR *100 + ZSTD_VERSION_RELEASE)
72ZSTDLIB_API unsigned ZSTD_versionNumber (void);
73
74
75/* *************************************
76*  Simple functions
77***************************************/
78/*! ZSTD_compress() :
79    Compresses `srcSize` bytes from buffer `src` into buffer `dst` of size `dstCapacity`.
80    Destination buffer must be already allocated.
81    Compression runs faster if `dstCapacity` >=  `ZSTD_compressBound(srcSize)`.
82    @return : the number of bytes written into `dst`,
83              or an error code if it fails (which can be tested using ZSTD_isError()) */
84ZSTDLIB_API size_t ZSTD_compress(   void* dst, size_t dstCapacity,
85                              const void* src, size_t srcSize,
86                                     int  compressionLevel);
87
88/** ZSTD_getDecompressedSize() :
89*   @return : decompressed size if known, 0 otherwise.
90        note : to know precise reason why result is `0`, follow up with ZSTD_getFrameParams() */
91unsigned long long ZSTD_getDecompressedSize(const void* src, size_t srcSize);
92
93/*! ZSTD_decompress() :
94    `compressedSize` : is the _exact_ size of compressed input, otherwise decompression will fail.
95    `dstCapacity` must be equal or larger than originalSize.
96    @return : the number of bytes decompressed into `dst` (<= `dstCapacity`),
97              or an errorCode if it fails (which can be tested using ZSTD_isError()) */
98ZSTDLIB_API size_t ZSTD_decompress( void* dst, size_t dstCapacity,
99                              const void* src, size_t compressedSize);
100
101
102/* *************************************
103*  Helper functions
104***************************************/
105ZSTDLIB_API size_t      ZSTD_compressBound(size_t srcSize); /*!< maximum compressed size (worst case scenario) */
106
107/* Error Management */
108ZSTDLIB_API unsigned    ZSTD_isError(size_t code);          /*!< tells if a `size_t` function result is an error code */
109ZSTDLIB_API const char* ZSTD_getErrorName(size_t code);     /*!< provides readable string for an error code */
110
111
112/* *************************************
113*  Explicit memory management
114***************************************/
115/** Compression context */
116typedef struct ZSTD_CCtx_s ZSTD_CCtx;                       /*< incomplete type */
117ZSTDLIB_API ZSTD_CCtx* ZSTD_createCCtx(void);
118ZSTDLIB_API size_t     ZSTD_freeCCtx(ZSTD_CCtx* cctx);      /*!< @return : errorCode */
119
120/** ZSTD_compressCCtx() :
121    Same as ZSTD_compress(), but requires an already allocated ZSTD_CCtx (see ZSTD_createCCtx()) */
122ZSTDLIB_API size_t ZSTD_compressCCtx(ZSTD_CCtx* ctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize, int compressionLevel);
123
124/** Decompression context */
125typedef struct ZSTD_DCtx_s ZSTD_DCtx;
126ZSTDLIB_API ZSTD_DCtx* ZSTD_createDCtx(void);
127ZSTDLIB_API size_t     ZSTD_freeDCtx(ZSTD_DCtx* dctx);      /*!< @return : errorCode */
128
129/** ZSTD_decompressDCtx() :
130*   Same as ZSTD_decompress(), but requires an already allocated ZSTD_DCtx (see ZSTD_createDCtx()) */
131ZSTDLIB_API size_t ZSTD_decompressDCtx(ZSTD_DCtx* ctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize);
132
133
134/*-************************
135*  Simple dictionary API
136***************************/
137/*! ZSTD_compress_usingDict() :
138*   Compression using a pre-defined Dictionary content (see dictBuilder).
139*   Note 1 : This function load the dictionary, resulting in a significant startup time.
140*   Note 2 : `dict` must remain accessible and unmodified during compression operation.
141*   Note 3 : `dict` can be `NULL`, in which case, it's equivalent to ZSTD_compressCCtx() */
142ZSTDLIB_API size_t ZSTD_compress_usingDict(ZSTD_CCtx* ctx,
143                                           void* dst, size_t dstCapacity,
144                                     const void* src, size_t srcSize,
145                                     const void* dict,size_t dictSize,
146                                           int compressionLevel);
147
148/*! ZSTD_decompress_usingDict() :
149*   Decompression using a pre-defined Dictionary content (see dictBuilder).
150*   Dictionary must be identical to the one used during compression.
151*   Note 1 : This function load the dictionary, resulting in a significant startup time
152*   Note 2 : `dict` must remain accessible and unmodified during compression operation.
153*   Note 3 : `dict` can be `NULL`, in which case, it's equivalent to ZSTD_decompressDCtx() */
154ZSTDLIB_API size_t ZSTD_decompress_usingDict(ZSTD_DCtx* dctx,
155                                             void* dst, size_t dstCapacity,
156                                       const void* src, size_t srcSize,
157                                       const void* dict,size_t dictSize);
158
159
160/*-**************************
161*  Advanced Dictionary API
162****************************/
163/*! ZSTD_createCDict() :
164*   Create a digested dictionary, ready to start compression operation without startup delay.
165*   `dict` can be released after creation */
166typedef struct ZSTD_CDict_s ZSTD_CDict;
167ZSTDLIB_API ZSTD_CDict* ZSTD_createCDict(const void* dict, size_t dictSize, int compressionLevel);
168ZSTDLIB_API size_t      ZSTD_freeCDict(ZSTD_CDict* CDict);
169
170/*! ZSTD_compress_usingCDict() :
171*   Compression using a pre-digested Dictionary.
172*   Much faster than ZSTD_compress_usingDict() when same dictionary is used multiple times.
173*   Note that compression level is decided during dictionary creation */
174ZSTDLIB_API size_t ZSTD_compress_usingCDict(ZSTD_CCtx* cctx,
175                                            void* dst, size_t dstCapacity,
176                                      const void* src, size_t srcSize,
177                                      const ZSTD_CDict* cdict);
178
179/*! ZSTD_createDDict() :
180*   Create a digested dictionary, ready to start decompression operation without startup delay.
181*   `dict` can be released after creation */
182typedef struct ZSTD_DDict_s ZSTD_DDict;
183ZSTDLIB_API ZSTD_DDict* ZSTD_createDDict(const void* dict, size_t dictSize);
184ZSTDLIB_API size_t      ZSTD_freeDDict(ZSTD_DDict* ddict);
185
186/*! ZSTD_decompress_usingDDict() :
187*   Decompression using a pre-digested Dictionary
188*   Much faster than ZSTD_decompress_usingDict() when same dictionary is used multiple times. */
189ZSTDLIB_API size_t ZSTD_decompress_usingDDict(ZSTD_DCtx* dctx,
190                                              void* dst, size_t dstCapacity,
191                                        const void* src, size_t srcSize,
192                                        const ZSTD_DDict* ddict);
193
194
195
196#ifdef ZSTD_STATIC_LINKING_ONLY
197
198/* ====================================================================================
199 * The definitions in this section are considered experimental.
200 * They should never be used with a dynamic library, as they may change in the future.
201 * They are provided for advanced usages.
202 * Use them only in association with static linking.
203 * ==================================================================================== */
204
205/*--- Constants ---*/
206#define ZSTD_MAGICNUMBER            0xFD2FB527   /* v0.7 */
207#define ZSTD_MAGIC_SKIPPABLE_START  0x184D2A50U
208
209#define ZSTD_WINDOWLOG_MAX_32  25
210#define ZSTD_WINDOWLOG_MAX_64  27
211#define ZSTD_WINDOWLOG_MAX    ((U32)(MEM_32bits() ? ZSTD_WINDOWLOG_MAX_32 : ZSTD_WINDOWLOG_MAX_64))
212#define ZSTD_WINDOWLOG_MIN     18
213#define ZSTD_CHAINLOG_MAX     (ZSTD_WINDOWLOG_MAX+1)
214#define ZSTD_CHAINLOG_MIN       4
215#define ZSTD_HASHLOG_MAX       ZSTD_WINDOWLOG_MAX
216#define ZSTD_HASHLOG_MIN       12
217#define ZSTD_HASHLOG3_MAX      17
218//#define ZSTD_HASHLOG3_MIN      15
219#define ZSTD_SEARCHLOG_MAX    (ZSTD_WINDOWLOG_MAX-1)
220#define ZSTD_SEARCHLOG_MIN      1
221#define ZSTD_SEARCHLENGTH_MAX   7
222#define ZSTD_SEARCHLENGTH_MIN   3
223#define ZSTD_TARGETLENGTH_MIN   4
224#define ZSTD_TARGETLENGTH_MAX 999
225
226#define ZSTD_FRAMEHEADERSIZE_MAX 18    /* for static allocation */
227static const size_t ZSTD_frameHeaderSize_min = 5;
228static const size_t ZSTD_frameHeaderSize_max = ZSTD_FRAMEHEADERSIZE_MAX;
229static const size_t ZSTD_skippableHeaderSize = 8;  /* magic number + skippable frame length */
230
231
232/*--- Types ---*/
233typedef enum { ZSTD_fast, ZSTD_dfast, ZSTD_greedy, ZSTD_lazy, ZSTD_lazy2, ZSTD_btlazy2, ZSTD_btopt } ZSTD_strategy;   /*< from faster to stronger */
234
235typedef struct {
236    unsigned windowLog;      /*< largest match distance : larger == more compression, more memory needed during decompression */
237    unsigned chainLog;       /*< fully searched segment : larger == more compression, slower, more memory (useless for fast) */
238    unsigned hashLog;        /*< dispatch table : larger == faster, more memory */
239    unsigned searchLog;      /*< nb of searches : larger == more compression, slower */
240    unsigned searchLength;   /*< match length searched : larger == faster decompression, sometimes less compression */
241    unsigned targetLength;   /*< acceptable match size for optimal parser (only) : larger == more compression, slower */
242    ZSTD_strategy strategy;
243} ZSTD_compressionParameters;
244
245typedef struct {
246    unsigned contentSizeFlag; /*< 1: content size will be in frame header (if known). */
247    unsigned checksumFlag;    /*< 1: will generate a 22-bits checksum at end of frame, to be used for error detection by decompressor */
248    unsigned noDictIDFlag;    /*< 1: no dict ID will be saved into frame header (if dictionary compression) */
249} ZSTD_frameParameters;
250
251typedef struct {
252    ZSTD_compressionParameters cParams;
253    ZSTD_frameParameters fParams;
254} ZSTD_parameters;
255
256/* custom memory allocation functions */
257typedef void* (*ZSTD_allocFunction) (void* opaque, size_t size);
258typedef void  (*ZSTD_freeFunction) (void* opaque, void* address);
259typedef struct { ZSTD_allocFunction customAlloc; ZSTD_freeFunction customFree; void* opaque; } ZSTD_customMem;
260
261
262/*-*************************************
263*  Advanced compression functions
264***************************************/
265/*! ZSTD_estimateCCtxSize() :
266 *  Gives the amount of memory allocated for a ZSTD_CCtx given a set of compression parameters.
267 *  `frameContentSize` is an optional parameter, provide `0` if unknown */
268ZSTDLIB_API size_t ZSTD_estimateCCtxSize(ZSTD_compressionParameters cParams);
269
270/*! ZSTD_createCCtx_advanced() :
271 *  Create a ZSTD compression context using external alloc and free functions */
272ZSTDLIB_API ZSTD_CCtx* ZSTD_createCCtx_advanced(ZSTD_customMem customMem);
273
274/*! ZSTD_createCDict_advanced() :
275 *  Create a ZSTD_CDict using external alloc and free, and customized compression parameters */
276ZSTDLIB_API ZSTD_CDict* ZSTD_createCDict_advanced(const void* dict, size_t dictSize,
277                                                  ZSTD_parameters params, ZSTD_customMem customMem);
278
279/*! ZSTD_sizeofCCtx() :
280 *  Gives the amount of memory used by a given ZSTD_CCtx */
281ZSTDLIB_API size_t ZSTD_sizeofCCtx(const ZSTD_CCtx* cctx);
282
283ZSTDLIB_API unsigned ZSTD_maxCLevel (void);
284
285/*! ZSTD_getParams() :
286*   same as ZSTD_getCParams(), but @return a full `ZSTD_parameters` object instead of a `ZSTD_compressionParameters`.
287*   All fields of `ZSTD_frameParameters` are set to default (0) */
288ZSTD_parameters ZSTD_getParams(int compressionLevel, unsigned long long srcSize, size_t dictSize);
289
290/*! ZSTD_getCParams() :
291*   @return ZSTD_compressionParameters structure for a selected compression level and srcSize.
292*   `srcSize` value is optional, select 0 if not known */
293ZSTDLIB_API ZSTD_compressionParameters ZSTD_getCParams(int compressionLevel, unsigned long long srcSize, size_t dictSize);
294
295/*! ZSTD_checkCParams() :
296*   Ensure param values remain within authorized range */
297ZSTDLIB_API size_t ZSTD_checkCParams(ZSTD_compressionParameters params);
298
299/*! ZSTD_adjustCParams() :
300*   optimize params for a given `srcSize` and `dictSize`.
301*   both values are optional, select `0` if unknown. */
302ZSTDLIB_API ZSTD_compressionParameters ZSTD_adjustCParams(ZSTD_compressionParameters cPar, unsigned long long srcSize, size_t dictSize);
303
304/*! ZSTD_compress_advanced() :
305*   Same as ZSTD_compress_usingDict(), with fine-tune control of each compression parameter */
306ZSTDLIB_API size_t ZSTD_compress_advanced (ZSTD_CCtx* ctx,
307                                           void* dst, size_t dstCapacity,
308                                     const void* src, size_t srcSize,
309                                     const void* dict,size_t dictSize,
310                                           ZSTD_parameters params);
311
312
313/*--- Advanced Decompression functions ---*/
314
315/*! ZSTD_estimateDCtxSize() :
316 *  Gives the potential amount of memory allocated to create a ZSTD_DCtx */
317ZSTDLIB_API size_t ZSTD_estimateDCtxSize(void);
318
319/*! ZSTD_createDCtx_advanced() :
320 *  Create a ZSTD decompression context using external alloc and free functions */
321ZSTDLIB_API ZSTD_DCtx* ZSTD_createDCtx_advanced(ZSTD_customMem customMem);
322
323/*! ZSTD_sizeofDCtx() :
324 *  Gives the amount of memory used by a given ZSTD_DCtx */
325ZSTDLIB_API size_t ZSTD_sizeofDCtx(const ZSTD_DCtx* dctx);
326
327
328/* ******************************************************************
329*  Streaming functions (direct mode - synchronous and buffer-less)
330********************************************************************/
331ZSTDLIB_API size_t ZSTD_compressBegin(ZSTD_CCtx* cctx, int compressionLevel);
332ZSTDLIB_API size_t ZSTD_compressBegin_usingDict(ZSTD_CCtx* cctx, const void* dict, size_t dictSize, int compressionLevel);
333ZSTDLIB_API size_t ZSTD_compressBegin_advanced(ZSTD_CCtx* cctx, const void* dict, size_t dictSize, ZSTD_parameters params, unsigned long long pledgedSrcSize);
334ZSTDLIB_API size_t ZSTD_copyCCtx(ZSTD_CCtx* cctx, const ZSTD_CCtx* preparedCCtx);
335
336ZSTDLIB_API size_t ZSTD_compressContinue(ZSTD_CCtx* cctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize);
337ZSTDLIB_API size_t ZSTD_compressEnd(ZSTD_CCtx* cctx, void* dst, size_t dstCapacity);
338
339/*
340  A ZSTD_CCtx object is required to track streaming operations.
341  Use ZSTD_createCCtx() / ZSTD_freeCCtx() to manage resource.
342  ZSTD_CCtx object can be re-used multiple times within successive compression operations.
343
344  Start by initializing a context.
345  Use ZSTD_compressBegin(), or ZSTD_compressBegin_usingDict() for dictionary compression,
346  or ZSTD_compressBegin_advanced(), for finer parameter control.
347  It's also possible to duplicate a reference context which has already been initialized, using ZSTD_copyCCtx()
348
349  Then, consume your input using ZSTD_compressContinue().
350  There are some important considerations to keep in mind when using this advanced function :
351  - ZSTD_compressContinue() has no internal buffer. It uses externally provided buffer only.
352  - Interface is synchronous : input is consumed entirely and produce 1 (or more) compressed blocks.
353  - Caller must ensure there is enough space in `dst` to store compressed data under worst case scenario.
354    Worst case evaluation is provided by ZSTD_compressBound().
355    ZSTD_compressContinue() doesn't guarantee recover after a failed compression.
356  - ZSTD_compressContinue() presumes prior input ***is still accessible and unmodified*** (up to maximum distance size, see WindowLog).
357    It remembers all previous contiguous blocks, plus one separated memory segment (which can itself consists of multiple contiguous blocks)
358  - ZSTD_compressContinue() detects that prior input has been overwritten when `src` buffer overlaps.
359    In which case, it will "discard" the relevant memory section from its history.
360
361
362  Finish a frame with ZSTD_compressEnd(), which will write the epilogue.
363  Without epilogue, frames will be considered unfinished (broken) by decoders.
364
365  You can then reuse `ZSTD_CCtx` (ZSTD_compressBegin()) to compress some new frame.
366*/
367
368typedef struct {
369    unsigned long long frameContentSize;
370    unsigned windowSize;
371    unsigned dictID;
372    unsigned checksumFlag;
373} ZSTD_frameParams;
374
375ZSTDLIB_API size_t ZSTD_getFrameParams(ZSTD_frameParams* fparamsPtr, const void* src, size_t srcSize);   /**< doesn't consume input */
376
377ZSTDLIB_API size_t ZSTD_decompressBegin(ZSTD_DCtx* dctx);
378ZSTDLIB_API size_t ZSTD_decompressBegin_usingDict(ZSTD_DCtx* dctx, const void* dict, size_t dictSize);
379ZSTDLIB_API void   ZSTD_copyDCtx(ZSTD_DCtx* dctx, const ZSTD_DCtx* preparedDCtx);
380
381ZSTDLIB_API size_t ZSTD_nextSrcSizeToDecompress(ZSTD_DCtx* dctx);
382ZSTDLIB_API size_t ZSTD_decompressContinue(ZSTD_DCtx* dctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize);
383
384/*
385  Streaming decompression, direct mode (bufferless)
386
387  A ZSTD_DCtx object is required to track streaming operations.
388  Use ZSTD_createDCtx() / ZSTD_freeDCtx() to manage it.
389  A ZSTD_DCtx object can be re-used multiple times.
390
391  First optional operation is to retrieve frame parameters, using ZSTD_getFrameParams(), which doesn't consume the input.
392  It can provide the minimum size of rolling buffer required to properly decompress data (`windowSize`),
393  and optionally the final size of uncompressed content.
394  (Note : content size is an optional info that may not be present. 0 means : content size unknown)
395  Frame parameters are extracted from the beginning of compressed frame.
396  The amount of data to read is variable, from ZSTD_frameHeaderSize_min to ZSTD_frameHeaderSize_max (so if `srcSize` >= ZSTD_frameHeaderSize_max, it will always work)
397  If `srcSize` is too small for operation to succeed, function will return the minimum size it requires to produce a result.
398  Result : 0 when successful, it means the ZSTD_frameParams structure has been filled.
399          >0 : means there is not enough data into `src`. Provides the expected size to successfully decode header.
400           errorCode, which can be tested using ZSTD_isError()
401
402  Start decompression, with ZSTD_decompressBegin() or ZSTD_decompressBegin_usingDict().
403  Alternatively, you can copy a prepared context, using ZSTD_copyDCtx().
404
405  Then use ZSTD_nextSrcSizeToDecompress() and ZSTD_decompressContinue() alternatively.
406  ZSTD_nextSrcSizeToDecompress() tells how much bytes to provide as 'srcSize' to ZSTD_decompressContinue().
407  ZSTD_decompressContinue() requires this exact amount of bytes, or it will fail.
408
409  @result of ZSTD_decompressContinue() is the number of bytes regenerated within 'dst' (necessarily <= dstCapacity).
410  It can be zero, which is not an error; it just means ZSTD_decompressContinue() has decoded some header.
411
412  ZSTD_decompressContinue() needs previous data blocks during decompression, up to `windowSize`.
413  They should preferably be located contiguously, prior to current block.
414  Alternatively, a round buffer of sufficient size is also possible. Sufficient size is determined by frame parameters.
415  ZSTD_decompressContinue() is very sensitive to contiguity,
416  if 2 blocks don't follow each other, make sure that either the compressor breaks contiguity at the same place,
417    or that previous contiguous segment is large enough to properly handle maximum back-reference.
418
419  A frame is fully decoded when ZSTD_nextSrcSizeToDecompress() returns zero.
420  Context can then be reset to start a new decompression.
421
422
423  == Special case : skippable frames ==
424
425  Skippable frames allow the integration of user-defined data into a flow of concatenated frames.
426  Skippable frames will be ignored (skipped) by a decompressor. The format of skippable frame is following:
427  a) Skippable frame ID - 4 Bytes, Little endian format, any value from 0x184D2A50 to 0x184D2A5F
428  b) Frame Size - 4 Bytes, Little endian format, unsigned 32-bits
429  c) Frame Content - any content (User Data) of length equal to Frame Size
430  For skippable frames ZSTD_decompressContinue() always returns 0.
431  For skippable frames ZSTD_getFrameParams() returns fparamsPtr->windowLog==0 what means that a frame is skippable.
432  It also returns Frame Size as fparamsPtr->frameContentSize.
433*/
434
435
436/* **************************************
437*  Block functions
438****************************************/
439/*! Block functions produce and decode raw zstd blocks, without frame metadata.
440    Frame metadata cost is typically ~18 bytes, which is non-negligible on very small blocks.
441    User will have to take in charge required information to regenerate data, such as compressed and content sizes.
442
443    A few rules to respect :
444    - Uncompressed block size must be <= MIN (128 KB, 1 << windowLog)
445      + If you need to compress more, cut data into multiple blocks
446      + Consider using the regular ZSTD_compress() instead, as frame metadata costs become negligible when source size is large.
447    - Compressing and decompressing require a context structure
448      + Use ZSTD_createCCtx() and ZSTD_createDCtx()
449    - It is necessary to init context before starting
450      + compression : ZSTD_compressBegin()
451      + decompression : ZSTD_decompressBegin()
452      + variants _usingDict() are also allowed
453      + copyCCtx() and copyDCtx() work too
454    - When a block is considered not compressible enough, ZSTD_compressBlock() result will be zero.
455      In which case, nothing is produced into `dst`.
456      + User must test for such outcome and deal directly with uncompressed data
457      + ZSTD_decompressBlock() doesn't accept uncompressed data as input !!!
458      + In case of multiple successive blocks, decoder must be informed of uncompressed block existence to follow proper history.
459        Use ZSTD_insertBlock() in such a case.
460        Insert block once it's copied into its final position.
461*/
462
463#define ZSTD_BLOCKSIZE_MAX (128 * 1024)   /* define, for static allocation */
464ZSTDLIB_API size_t ZSTD_compressBlock  (ZSTD_CCtx* cctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize);
465ZSTDLIB_API size_t ZSTD_decompressBlock(ZSTD_DCtx* dctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize);
466ZSTDLIB_API size_t ZSTD_insertBlock(ZSTD_DCtx* dctx, const void* blockStart, size_t blockSize);  /**< insert block into `dctx` history. Useful to track uncompressed blocks */
467
468
469#endif   /* ZSTD_STATIC_LINKING_ONLY */
470
471#if defined (__cplusplus)
472}
473#endif
474
475#endif  /* ZSTD_H_235446 */
Note: See TracBrowser for help on using the repository browser.