648db22b |
1 | /* |
2 | * Copyright (c) Yann Collet, Meta Platforms, Inc. and affiliates. |
3 | * All rights reserved. |
4 | * |
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. |
9 | */ |
10 | |
11 | #ifndef ZSTDv06_H |
12 | #define ZSTDv06_H |
13 | |
14 | #if defined (__cplusplus) |
15 | extern "C" { |
16 | #endif |
17 | |
18 | /*====== Dependency ======*/ |
19 | #include <stddef.h> /* size_t */ |
20 | |
21 | |
22 | /*====== Export for Windows ======*/ |
23 | /*! |
24 | * ZSTDv06_DLL_EXPORT : |
25 | * Enable exporting of functions when building a Windows DLL |
26 | */ |
27 | #if defined(_WIN32) && defined(ZSTDv06_DLL_EXPORT) && (ZSTDv06_DLL_EXPORT==1) |
28 | # define ZSTDLIBv06_API __declspec(dllexport) |
29 | #else |
30 | # define ZSTDLIBv06_API |
31 | #endif |
32 | |
33 | |
34 | /* ************************************* |
35 | * Simple functions |
36 | ***************************************/ |
37 | /*! ZSTDv06_decompress() : |
38 | `compressedSize` : is the _exact_ size of the compressed blob, otherwise decompression will fail. |
39 | `dstCapacity` must be large enough, equal or larger than originalSize. |
40 | @return : the number of bytes decompressed into `dst` (<= `dstCapacity`), |
41 | or an errorCode if it fails (which can be tested using ZSTDv06_isError()) */ |
42 | ZSTDLIBv06_API size_t ZSTDv06_decompress( void* dst, size_t dstCapacity, |
43 | const void* src, size_t compressedSize); |
44 | |
45 | /** |
46 | ZSTDv06_findFrameSizeInfoLegacy() : get the source length and decompressed bound of a ZSTD frame compliant with v0.6.x format |
47 | srcSize : The size of the 'src' buffer, at least as large as the frame pointed to by 'src' |
48 | cSize (output parameter) : the number of bytes that would be read to decompress this frame |
49 | or an error code if it fails (which can be tested using ZSTDv01_isError()) |
50 | dBound (output parameter) : an upper-bound for the decompressed size of the data in the frame |
51 | or ZSTD_CONTENTSIZE_ERROR if an error occurs |
52 | |
53 | note : assumes `cSize` and `dBound` are _not_ NULL. |
54 | */ |
55 | void ZSTDv06_findFrameSizeInfoLegacy(const void *src, size_t srcSize, |
56 | size_t* cSize, unsigned long long* dBound); |
57 | |
58 | /* ************************************* |
59 | * Helper functions |
60 | ***************************************/ |
61 | ZSTDLIBv06_API size_t ZSTDv06_compressBound(size_t srcSize); /*!< maximum compressed size (worst case scenario) */ |
62 | |
63 | /* Error Management */ |
64 | ZSTDLIBv06_API unsigned ZSTDv06_isError(size_t code); /*!< tells if a `size_t` function result is an error code */ |
65 | ZSTDLIBv06_API const char* ZSTDv06_getErrorName(size_t code); /*!< provides readable string for an error code */ |
66 | |
67 | |
68 | /* ************************************* |
69 | * Explicit memory management |
70 | ***************************************/ |
71 | /** Decompression context */ |
72 | typedef struct ZSTDv06_DCtx_s ZSTDv06_DCtx; |
73 | ZSTDLIBv06_API ZSTDv06_DCtx* ZSTDv06_createDCtx(void); |
74 | ZSTDLIBv06_API size_t ZSTDv06_freeDCtx(ZSTDv06_DCtx* dctx); /*!< @return : errorCode */ |
75 | |
76 | /** ZSTDv06_decompressDCtx() : |
77 | * Same as ZSTDv06_decompress(), but requires an already allocated ZSTDv06_DCtx (see ZSTDv06_createDCtx()) */ |
78 | ZSTDLIBv06_API size_t ZSTDv06_decompressDCtx(ZSTDv06_DCtx* ctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize); |
79 | |
80 | |
81 | /*-*********************** |
82 | * Dictionary API |
83 | *************************/ |
84 | /*! ZSTDv06_decompress_usingDict() : |
85 | * Decompression using a pre-defined Dictionary content (see dictBuilder). |
86 | * Dictionary must be identical to the one used during compression, otherwise regenerated data will be corrupted. |
87 | * Note : dict can be NULL, in which case, it's equivalent to ZSTDv06_decompressDCtx() */ |
88 | ZSTDLIBv06_API size_t ZSTDv06_decompress_usingDict(ZSTDv06_DCtx* dctx, |
89 | void* dst, size_t dstCapacity, |
90 | const void* src, size_t srcSize, |
91 | const void* dict,size_t dictSize); |
92 | |
93 | |
94 | /*-************************ |
95 | * Advanced Streaming API |
96 | ***************************/ |
97 | struct ZSTDv06_frameParams_s { unsigned long long frameContentSize; unsigned windowLog; }; |
98 | typedef struct ZSTDv06_frameParams_s ZSTDv06_frameParams; |
99 | |
100 | ZSTDLIBv06_API size_t ZSTDv06_getFrameParams(ZSTDv06_frameParams* fparamsPtr, const void* src, size_t srcSize); /**< doesn't consume input */ |
101 | ZSTDLIBv06_API size_t ZSTDv06_decompressBegin_usingDict(ZSTDv06_DCtx* dctx, const void* dict, size_t dictSize); |
102 | ZSTDLIBv06_API void ZSTDv06_copyDCtx(ZSTDv06_DCtx* dctx, const ZSTDv06_DCtx* preparedDCtx); |
103 | |
104 | ZSTDLIBv06_API size_t ZSTDv06_nextSrcSizeToDecompress(ZSTDv06_DCtx* dctx); |
105 | ZSTDLIBv06_API size_t ZSTDv06_decompressContinue(ZSTDv06_DCtx* dctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize); |
106 | |
107 | |
108 | |
109 | /* ************************************* |
110 | * ZBUFF API |
111 | ***************************************/ |
112 | |
113 | typedef struct ZBUFFv06_DCtx_s ZBUFFv06_DCtx; |
114 | ZSTDLIBv06_API ZBUFFv06_DCtx* ZBUFFv06_createDCtx(void); |
115 | ZSTDLIBv06_API size_t ZBUFFv06_freeDCtx(ZBUFFv06_DCtx* dctx); |
116 | |
117 | ZSTDLIBv06_API size_t ZBUFFv06_decompressInit(ZBUFFv06_DCtx* dctx); |
118 | ZSTDLIBv06_API size_t ZBUFFv06_decompressInitDictionary(ZBUFFv06_DCtx* dctx, const void* dict, size_t dictSize); |
119 | |
120 | ZSTDLIBv06_API size_t ZBUFFv06_decompressContinue(ZBUFFv06_DCtx* dctx, |
121 | void* dst, size_t* dstCapacityPtr, |
122 | const void* src, size_t* srcSizePtr); |
123 | |
124 | /*-*************************************************************************** |
125 | * Streaming decompression howto |
126 | * |
127 | * A ZBUFFv06_DCtx object is required to track streaming operations. |
128 | * Use ZBUFFv06_createDCtx() and ZBUFFv06_freeDCtx() to create/release resources. |
129 | * Use ZBUFFv06_decompressInit() to start a new decompression operation, |
130 | * or ZBUFFv06_decompressInitDictionary() if decompression requires a dictionary. |
131 | * Note that ZBUFFv06_DCtx objects can be re-init multiple times. |
132 | * |
133 | * Use ZBUFFv06_decompressContinue() repetitively to consume your input. |
134 | * *srcSizePtr and *dstCapacityPtr can be any size. |
135 | * The function will report how many bytes were read or written by modifying *srcSizePtr and *dstCapacityPtr. |
136 | * Note that it may not consume the entire input, in which case it's up to the caller to present remaining input again. |
137 | * The content of `dst` will be overwritten (up to *dstCapacityPtr) at each function call, so save its content if it matters, or change `dst`. |
138 | * @return : a hint to preferred nb of bytes to use as input for next function call (it's only a hint, to help latency), |
139 | * or 0 when a frame is completely decoded, |
140 | * or an error code, which can be tested using ZBUFFv06_isError(). |
141 | * |
142 | * Hint : recommended buffer sizes (not compulsory) : ZBUFFv06_recommendedDInSize() and ZBUFFv06_recommendedDOutSize() |
143 | * output : ZBUFFv06_recommendedDOutSize== 128 KB block size is the internal unit, it ensures it's always possible to write a full block when decoded. |
144 | * input : ZBUFFv06_recommendedDInSize == 128KB + 3; |
145 | * just follow indications from ZBUFFv06_decompressContinue() to minimize latency. It should always be <= 128 KB + 3 . |
146 | * *******************************************************************************/ |
147 | |
148 | |
149 | /* ************************************* |
150 | * Tool functions |
151 | ***************************************/ |
152 | ZSTDLIBv06_API unsigned ZBUFFv06_isError(size_t errorCode); |
153 | ZSTDLIBv06_API const char* ZBUFFv06_getErrorName(size_t errorCode); |
154 | |
155 | /** Functions below provide recommended buffer sizes for Compression or Decompression operations. |
156 | * These sizes are just hints, they tend to offer better latency */ |
157 | ZSTDLIBv06_API size_t ZBUFFv06_recommendedDInSize(void); |
158 | ZSTDLIBv06_API size_t ZBUFFv06_recommendedDOutSize(void); |
159 | |
160 | |
161 | /*-************************************* |
162 | * Constants |
163 | ***************************************/ |
164 | #define ZSTDv06_MAGICNUMBER 0xFD2FB526 /* v0.6 */ |
165 | |
166 | |
167 | |
168 | #if defined (__cplusplus) |
169 | } |
170 | #endif |
171 | |
172 | #endif /* ZSTDv06_BUFFERED_H */ |