1 /** |
|
2 * Copyright (c) 2016-present, Yann Collet, Facebook, Inc. |
|
3 * All rights reserved. |
|
4 * |
|
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. |
|
8 */ |
|
9 |
|
10 /* *************************************************************** |
|
11 * NOTES/WARNINGS |
|
12 *****************************************************************/ |
|
13 /* The streaming API defined here will soon be deprecated by the |
|
14 * new one in 'zstd.h'; consider migrating towards newer streaming |
|
15 * API. See 'lib/README.md'. |
|
16 *****************************************************************/ |
|
17 |
|
18 #ifndef ZSTD_BUFFERED_H_23987 |
|
19 #define ZSTD_BUFFERED_H_23987 |
|
20 |
|
21 #if defined (__cplusplus) |
|
22 extern "C" { |
|
23 #endif |
|
24 |
|
25 /* ************************************* |
|
26 * Dependencies |
|
27 ***************************************/ |
|
28 #include <stddef.h> /* size_t */ |
|
29 |
|
30 |
|
31 /* *************************************************************** |
|
32 * Compiler specifics |
|
33 *****************************************************************/ |
|
34 /* ZSTD_DLL_EXPORT : |
|
35 * Enable exporting of functions when building a Windows DLL */ |
|
36 #if defined(_WIN32) && defined(ZSTD_DLL_EXPORT) && (ZSTD_DLL_EXPORT==1) |
|
37 # define ZSTDLIB_API __declspec(dllexport) |
|
38 #else |
|
39 # define ZSTDLIB_API |
|
40 #endif |
|
41 |
|
42 |
|
43 /* ************************************* |
|
44 * Streaming functions |
|
45 ***************************************/ |
|
46 /* This is the easier "buffered" streaming API, |
|
47 * using an internal buffer to lift all restrictions on user-provided buffers |
|
48 * which can be any size, any place, for both input and output. |
|
49 * ZBUFF and ZSTD are 100% interoperable, |
|
50 * frames created by one can be decoded by the other one */ |
|
51 |
|
52 typedef struct ZBUFF_CCtx_s ZBUFF_CCtx; |
|
53 ZSTDLIB_API ZBUFF_CCtx* ZBUFF_createCCtx(void); |
|
54 ZSTDLIB_API size_t ZBUFF_freeCCtx(ZBUFF_CCtx* cctx); |
|
55 |
|
56 ZSTDLIB_API size_t ZBUFF_compressInit(ZBUFF_CCtx* cctx, int compressionLevel); |
|
57 ZSTDLIB_API size_t ZBUFF_compressInitDictionary(ZBUFF_CCtx* cctx, const void* dict, size_t dictSize, int compressionLevel); |
|
58 |
|
59 ZSTDLIB_API size_t ZBUFF_compressContinue(ZBUFF_CCtx* cctx, void* dst, size_t* dstCapacityPtr, const void* src, size_t* srcSizePtr); |
|
60 ZSTDLIB_API size_t ZBUFF_compressFlush(ZBUFF_CCtx* cctx, void* dst, size_t* dstCapacityPtr); |
|
61 ZSTDLIB_API size_t ZBUFF_compressEnd(ZBUFF_CCtx* cctx, void* dst, size_t* dstCapacityPtr); |
|
62 |
|
63 /*-************************************************* |
|
64 * Streaming compression - howto |
|
65 * |
|
66 * A ZBUFF_CCtx object is required to track streaming operation. |
|
67 * Use ZBUFF_createCCtx() and ZBUFF_freeCCtx() to create/release resources. |
|
68 * ZBUFF_CCtx objects can be reused multiple times. |
|
69 * |
|
70 * Start by initializing ZBUF_CCtx. |
|
71 * Use ZBUFF_compressInit() to start a new compression operation. |
|
72 * Use ZBUFF_compressInitDictionary() for a compression which requires a dictionary. |
|
73 * |
|
74 * Use ZBUFF_compressContinue() repetitively to consume input stream. |
|
75 * *srcSizePtr and *dstCapacityPtr can be any size. |
|
76 * The function will report how many bytes were read or written within *srcSizePtr and *dstCapacityPtr. |
|
77 * Note that it may not consume the entire input, in which case it's up to the caller to present again remaining data. |
|
78 * The content of `dst` will be overwritten (up to *dstCapacityPtr) at each call, so save its content if it matters or change @dst . |
|
79 * @return : a hint to preferred nb of bytes to use as input for next function call (it's just a hint, to improve latency) |
|
80 * or an error code, which can be tested using ZBUFF_isError(). |
|
81 * |
|
82 * At any moment, it's possible to flush whatever data remains within buffer, using ZBUFF_compressFlush(). |
|
83 * The nb of bytes written into `dst` will be reported into *dstCapacityPtr. |
|
84 * Note that the function cannot output more than *dstCapacityPtr, |
|
85 * therefore, some content might still be left into internal buffer if *dstCapacityPtr is too small. |
|
86 * @return : nb of bytes still present into internal buffer (0 if it's empty) |
|
87 * or an error code, which can be tested using ZBUFF_isError(). |
|
88 * |
|
89 * ZBUFF_compressEnd() instructs to finish a frame. |
|
90 * It will perform a flush and write frame epilogue. |
|
91 * The epilogue is required for decoders to consider a frame completed. |
|
92 * Similar to ZBUFF_compressFlush(), it may not be able to output the entire internal buffer content if *dstCapacityPtr is too small. |
|
93 * In which case, call again ZBUFF_compressFlush() to complete the flush. |
|
94 * @return : nb of bytes still present into internal buffer (0 if it's empty) |
|
95 * or an error code, which can be tested using ZBUFF_isError(). |
|
96 * |
|
97 * Hint : _recommended buffer_ sizes (not compulsory) : ZBUFF_recommendedCInSize() / ZBUFF_recommendedCOutSize() |
|
98 * input : ZBUFF_recommendedCInSize==128 KB block size is the internal unit, use this value to reduce intermediate stages (better latency) |
|
99 * output : ZBUFF_recommendedCOutSize==ZSTD_compressBound(128 KB) + 3 + 3 : ensures it's always possible to write/flush/end a full block. Skip some buffering. |
|
100 * By using both, it ensures that input will be entirely consumed, and output will always contain the result, reducing intermediate buffering. |
|
101 * **************************************************/ |
|
102 |
|
103 |
|
104 typedef struct ZBUFF_DCtx_s ZBUFF_DCtx; |
|
105 ZSTDLIB_API ZBUFF_DCtx* ZBUFF_createDCtx(void); |
|
106 ZSTDLIB_API size_t ZBUFF_freeDCtx(ZBUFF_DCtx* dctx); |
|
107 |
|
108 ZSTDLIB_API size_t ZBUFF_decompressInit(ZBUFF_DCtx* dctx); |
|
109 ZSTDLIB_API size_t ZBUFF_decompressInitDictionary(ZBUFF_DCtx* dctx, const void* dict, size_t dictSize); |
|
110 |
|
111 ZSTDLIB_API size_t ZBUFF_decompressContinue(ZBUFF_DCtx* dctx, |
|
112 void* dst, size_t* dstCapacityPtr, |
|
113 const void* src, size_t* srcSizePtr); |
|
114 |
|
115 /*-*************************************************************************** |
|
116 * Streaming decompression howto |
|
117 * |
|
118 * A ZBUFF_DCtx object is required to track streaming operations. |
|
119 * Use ZBUFF_createDCtx() and ZBUFF_freeDCtx() to create/release resources. |
|
120 * Use ZBUFF_decompressInit() to start a new decompression operation, |
|
121 * or ZBUFF_decompressInitDictionary() if decompression requires a dictionary. |
|
122 * Note that ZBUFF_DCtx objects can be re-init multiple times. |
|
123 * |
|
124 * Use ZBUFF_decompressContinue() repetitively to consume your input. |
|
125 * *srcSizePtr and *dstCapacityPtr can be any size. |
|
126 * The function will report how many bytes were read or written by modifying *srcSizePtr and *dstCapacityPtr. |
|
127 * Note that it may not consume the entire input, in which case it's up to the caller to present remaining input again. |
|
128 * The content of `dst` will be overwritten (up to *dstCapacityPtr) at each function call, so save its content if it matters, or change `dst`. |
|
129 * @return : 0 when a frame is completely decoded and fully flushed, |
|
130 * 1 when there is still some data left within internal buffer to flush, |
|
131 * >1 when more data is expected, with value being a suggested next input size (it's just a hint, which helps latency), |
|
132 * or an error code, which can be tested using ZBUFF_isError(). |
|
133 * |
|
134 * Hint : recommended buffer sizes (not compulsory) : ZBUFF_recommendedDInSize() and ZBUFF_recommendedDOutSize() |
|
135 * output : ZBUFF_recommendedDOutSize== 128 KB block size is the internal unit, it ensures it's always possible to write a full block when decoded. |
|
136 * input : ZBUFF_recommendedDInSize == 128KB + 3; |
|
137 * just follow indications from ZBUFF_decompressContinue() to minimize latency. It should always be <= 128 KB + 3 . |
|
138 * *******************************************************************************/ |
|
139 |
|
140 |
|
141 /* ************************************* |
|
142 * Tool functions |
|
143 ***************************************/ |
|
144 ZSTDLIB_API unsigned ZBUFF_isError(size_t errorCode); |
|
145 ZSTDLIB_API const char* ZBUFF_getErrorName(size_t errorCode); |
|
146 |
|
147 /** Functions below provide recommended buffer sizes for Compression or Decompression operations. |
|
148 * These sizes are just hints, they tend to offer better latency */ |
|
149 ZSTDLIB_API size_t ZBUFF_recommendedCInSize(void); |
|
150 ZSTDLIB_API size_t ZBUFF_recommendedCOutSize(void); |
|
151 ZSTDLIB_API size_t ZBUFF_recommendedDInSize(void); |
|
152 ZSTDLIB_API size_t ZBUFF_recommendedDOutSize(void); |
|
153 |
|
154 |
|
155 #ifdef ZBUFF_STATIC_LINKING_ONLY |
|
156 |
|
157 /* ==================================================================================== |
|
158 * The definitions in this section are considered experimental. |
|
159 * They should never be used in association with a dynamic library, as they may change in the future. |
|
160 * They are provided for advanced usages. |
|
161 * Use them only in association with static linking. |
|
162 * ==================================================================================== */ |
|
163 |
|
164 /*--- Dependency ---*/ |
|
165 #define ZSTD_STATIC_LINKING_ONLY /* ZSTD_parameters, ZSTD_customMem */ |
|
166 #include "zstd.h" |
|
167 |
|
168 |
|
169 /*--- Custom memory allocator ---*/ |
|
170 /*! ZBUFF_createCCtx_advanced() : |
|
171 * Create a ZBUFF compression context using external alloc and free functions */ |
|
172 ZSTDLIB_API ZBUFF_CCtx* ZBUFF_createCCtx_advanced(ZSTD_customMem customMem); |
|
173 |
|
174 /*! ZBUFF_createDCtx_advanced() : |
|
175 * Create a ZBUFF decompression context using external alloc and free functions */ |
|
176 ZSTDLIB_API ZBUFF_DCtx* ZBUFF_createDCtx_advanced(ZSTD_customMem customMem); |
|
177 |
|
178 |
|
179 /*--- Advanced Streaming Initialization ---*/ |
|
180 ZSTDLIB_API size_t ZBUFF_compressInit_advanced(ZBUFF_CCtx* zbc, |
|
181 const void* dict, size_t dictSize, |
|
182 ZSTD_parameters params, unsigned long long pledgedSrcSize); |
|
183 |
|
184 #endif /* ZBUFF_STATIC_LINKING_ONLY */ |
|
185 |
|
186 |
|
187 #if defined (__cplusplus) |
|
188 } |
|
189 #endif |
|
190 |
|
191 #endif /* ZSTD_BUFFERED_H_23987 */ |
|