2 * Copyright (c) 2016-present, Yann Collet, Facebook, Inc.
5 * This source code is licensed under the BSD-style license found in the
6 * LICENSE file in the root directory of this source tree. An additional grant
7 * of patent rights can be found in the PATENTS file in the same directory.
13 #if defined (__cplusplus)
17 /*-*************************************
19 ***************************************/
20 #include <stddef.h> /* size_t */
21 #include "mem.h" /* U64, U32 */
24 /* *************************************
26 ***************************************/
27 /*! ZSTDv05_decompress() :
28 `compressedSize` : is the _exact_ size of the compressed blob, otherwise decompression will fail.
29 `dstCapacity` must be large enough, equal or larger than originalSize.
30 @return : the number of bytes decompressed into `dst` (<= `dstCapacity`),
31 or an errorCode if it fails (which can be tested using ZSTDv05_isError()) */
32 size_t ZSTDv05_decompress( void* dst
, size_t dstCapacity
,
33 const void* src
, size_t compressedSize
);
36 /* *************************************
38 ***************************************/
39 /* Error Management */
40 unsigned ZSTDv05_isError(size_t code
); /*!< tells if a `size_t` function result is an error code */
41 const char* ZSTDv05_getErrorName(size_t code
); /*!< provides readable string for an error code */
44 /* *************************************
45 * Explicit memory management
46 ***************************************/
47 /** Decompression context */
48 typedef struct ZSTDv05_DCtx_s ZSTDv05_DCtx
;
49 ZSTDv05_DCtx
* ZSTDv05_createDCtx(void);
50 size_t ZSTDv05_freeDCtx(ZSTDv05_DCtx
* dctx
); /*!< @return : errorCode */
52 /** ZSTDv05_decompressDCtx() :
53 * Same as ZSTDv05_decompress(), but requires an already allocated ZSTDv05_DCtx (see ZSTDv05_createDCtx()) */
54 size_t ZSTDv05_decompressDCtx(ZSTDv05_DCtx
* ctx
, void* dst
, size_t dstCapacity
, const void* src
, size_t srcSize
);
57 /*-***********************
58 * Simple Dictionary API
59 *************************/
60 /*! ZSTDv05_decompress_usingDict() :
61 * Decompression using a pre-defined Dictionary content (see dictBuilder).
62 * Dictionary must be identical to the one used during compression, otherwise regenerated data will be corrupted.
63 * Note : dict can be NULL, in which case, it's equivalent to ZSTDv05_decompressDCtx() */
64 size_t ZSTDv05_decompress_usingDict(ZSTDv05_DCtx
* dctx
,
65 void* dst
, size_t dstCapacity
,
66 const void* src
, size_t srcSize
,
67 const void* dict
,size_t dictSize
);
69 /*-************************
70 * Advanced Streaming API
71 ***************************/
72 typedef enum { ZSTDv05_fast
, ZSTDv05_greedy
, ZSTDv05_lazy
, ZSTDv05_lazy2
, ZSTDv05_btlazy2
, ZSTDv05_opt
, ZSTDv05_btopt
} ZSTDv05_strategy
;
75 U32 windowLog
; /* the only useful information to retrieve */
76 U32 contentLog
; U32 hashLog
; U32 searchLog
; U32 searchLength
; U32 targetLength
; ZSTDv05_strategy strategy
;
78 size_t ZSTDv05_getFrameParams(ZSTDv05_parameters
* params
, const void* src
, size_t srcSize
);
80 size_t ZSTDv05_decompressBegin_usingDict(ZSTDv05_DCtx
* dctx
, const void* dict
, size_t dictSize
);
81 void ZSTDv05_copyDCtx(ZSTDv05_DCtx
* dstDCtx
, const ZSTDv05_DCtx
* srcDCtx
);
82 size_t ZSTDv05_nextSrcSizeToDecompress(ZSTDv05_DCtx
* dctx
);
83 size_t ZSTDv05_decompressContinue(ZSTDv05_DCtx
* dctx
, void* dst
, size_t dstCapacity
, const void* src
, size_t srcSize
);
86 /*-***********************
88 *************************/
89 typedef struct ZBUFFv05_DCtx_s ZBUFFv05_DCtx
;
90 ZBUFFv05_DCtx
* ZBUFFv05_createDCtx(void);
91 size_t ZBUFFv05_freeDCtx(ZBUFFv05_DCtx
* dctx
);
93 size_t ZBUFFv05_decompressInit(ZBUFFv05_DCtx
* dctx
);
94 size_t ZBUFFv05_decompressInitDictionary(ZBUFFv05_DCtx
* dctx
, const void* dict
, size_t dictSize
);
96 size_t ZBUFFv05_decompressContinue(ZBUFFv05_DCtx
* dctx
,
97 void* dst
, size_t* dstCapacityPtr
,
98 const void* src
, size_t* srcSizePtr
);
100 /*-***************************************************************************
101 * Streaming decompression
103 * A ZBUFFv05_DCtx object is required to track streaming operations.
104 * Use ZBUFFv05_createDCtx() and ZBUFFv05_freeDCtx() to create/release resources.
105 * Use ZBUFFv05_decompressInit() to start a new decompression operation,
106 * or ZBUFFv05_decompressInitDictionary() if decompression requires a dictionary.
107 * Note that ZBUFFv05_DCtx objects can be reused multiple times.
109 * Use ZBUFFv05_decompressContinue() repetitively to consume your input.
110 * *srcSizePtr and *dstCapacityPtr can be any size.
111 * The function will report how many bytes were read or written by modifying *srcSizePtr and *dstCapacityPtr.
112 * Note that it may not consume the entire input, in which case it's up to the caller to present remaining input again.
113 * The content of @dst will be overwritten (up to *dstCapacityPtr) at each function call, so save its content if it matters or change @dst.
114 * @return : a hint to preferred nb of bytes to use as input for next function call (it's only a hint, to help latency)
115 * or 0 when a frame is completely decoded
116 * or an error code, which can be tested using ZBUFFv05_isError().
118 * Hint : recommended buffer sizes (not compulsory) : ZBUFFv05_recommendedDInSize() / ZBUFFv05_recommendedDOutSize()
119 * output : ZBUFFv05_recommendedDOutSize==128 KB block size is the internal unit, it ensures it's always possible to write a full block when decoded.
120 * input : ZBUFFv05_recommendedDInSize==128Kb+3; just follow indications from ZBUFFv05_decompressContinue() to minimize latency. It should always be <= 128 KB + 3 .
121 * *******************************************************************************/
124 /* *************************************
126 ***************************************/
127 unsigned ZBUFFv05_isError(size_t errorCode
);
128 const char* ZBUFFv05_getErrorName(size_t errorCode
);
130 /** Functions below provide recommended buffer sizes for Compression or Decompression operations.
131 * These sizes are just hints, and tend to offer better latency */
132 size_t ZBUFFv05_recommendedDInSize(void);
133 size_t ZBUFFv05_recommendedDOutSize(void);
137 /*-*************************************
139 ***************************************/
140 #define ZSTDv05_MAGICNUMBER 0xFD2FB525 /* v0.5 */
145 #if defined (__cplusplus)
149 #endif /* ZSTDv0505_H */