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