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 ZSTDv07_H_235446 |
12 | #define ZSTDv07_H_235446 |
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 | * ZSTDv07_DLL_EXPORT : |
25 | * Enable exporting of functions when building a Windows DLL |
26 | */ |
27 | #if defined(_WIN32) && defined(ZSTDv07_DLL_EXPORT) && (ZSTDv07_DLL_EXPORT==1) |
28 | # define ZSTDLIBv07_API __declspec(dllexport) |
29 | #else |
30 | # define ZSTDLIBv07_API |
31 | #endif |
32 | |
33 | |
34 | /* ************************************* |
35 | * Simple API |
36 | ***************************************/ |
37 | /*! ZSTDv07_getDecompressedSize() : |
38 | * @return : decompressed size if known, 0 otherwise. |
39 | note 1 : if `0`, follow up with ZSTDv07_getFrameParams() to know precise failure cause. |
40 | note 2 : decompressed size could be wrong or intentionally modified ! |
41 | always ensure results fit within application's authorized limits */ |
42 | unsigned long long ZSTDv07_getDecompressedSize(const void* src, size_t srcSize); |
43 | |
44 | /*! ZSTDv07_decompress() : |
45 | `compressedSize` : must be _exact_ size of compressed input, otherwise decompression will fail. |
46 | `dstCapacity` must be equal or larger than originalSize. |
47 | @return : the number of bytes decompressed into `dst` (<= `dstCapacity`), |
48 | or an errorCode if it fails (which can be tested using ZSTDv07_isError()) */ |
49 | ZSTDLIBv07_API size_t ZSTDv07_decompress( void* dst, size_t dstCapacity, |
50 | const void* src, size_t compressedSize); |
51 | |
52 | /** |
53 | ZSTDv07_findFrameSizeInfoLegacy() : get the source length and decompressed bound of a ZSTD frame compliant with v0.7.x format |
54 | srcSize : The size of the 'src' buffer, at least as large as the frame pointed to by 'src' |
55 | cSize (output parameter) : the number of bytes that would be read to decompress this frame |
56 | or an error code if it fails (which can be tested using ZSTDv01_isError()) |
57 | dBound (output parameter) : an upper-bound for the decompressed size of the data in the frame |
58 | or ZSTD_CONTENTSIZE_ERROR if an error occurs |
59 | |
60 | note : assumes `cSize` and `dBound` are _not_ NULL. |
61 | */ |
62 | void ZSTDv07_findFrameSizeInfoLegacy(const void *src, size_t srcSize, |
63 | size_t* cSize, unsigned long long* dBound); |
64 | |
65 | /*====== Helper functions ======*/ |
66 | ZSTDLIBv07_API unsigned ZSTDv07_isError(size_t code); /*!< tells if a `size_t` function result is an error code */ |
67 | ZSTDLIBv07_API const char* ZSTDv07_getErrorName(size_t code); /*!< provides readable string from an error code */ |
68 | |
69 | |
70 | /*-************************************* |
71 | * Explicit memory management |
72 | ***************************************/ |
73 | /** Decompression context */ |
74 | typedef struct ZSTDv07_DCtx_s ZSTDv07_DCtx; |
75 | ZSTDLIBv07_API ZSTDv07_DCtx* ZSTDv07_createDCtx(void); |
76 | ZSTDLIBv07_API size_t ZSTDv07_freeDCtx(ZSTDv07_DCtx* dctx); /*!< @return : errorCode */ |
77 | |
78 | /** ZSTDv07_decompressDCtx() : |
79 | * Same as ZSTDv07_decompress(), requires an allocated ZSTDv07_DCtx (see ZSTDv07_createDCtx()) */ |
80 | ZSTDLIBv07_API size_t ZSTDv07_decompressDCtx(ZSTDv07_DCtx* ctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize); |
81 | |
82 | |
83 | /*-************************ |
84 | * Simple dictionary API |
85 | ***************************/ |
86 | /*! ZSTDv07_decompress_usingDict() : |
87 | * Decompression using a pre-defined Dictionary content (see dictBuilder). |
88 | * Dictionary must be identical to the one used during compression. |
89 | * Note : This function load the dictionary, resulting in a significant startup time */ |
90 | ZSTDLIBv07_API size_t ZSTDv07_decompress_usingDict(ZSTDv07_DCtx* dctx, |
91 | void* dst, size_t dstCapacity, |
92 | const void* src, size_t srcSize, |
93 | const void* dict,size_t dictSize); |
94 | |
95 | |
96 | /*-************************** |
97 | * Advanced Dictionary API |
98 | ****************************/ |
99 | /*! ZSTDv07_createDDict() : |
100 | * Create a digested dictionary, ready to start decompression operation without startup delay. |
101 | * `dict` can be released after creation */ |
102 | typedef struct ZSTDv07_DDict_s ZSTDv07_DDict; |
103 | ZSTDLIBv07_API ZSTDv07_DDict* ZSTDv07_createDDict(const void* dict, size_t dictSize); |
104 | ZSTDLIBv07_API size_t ZSTDv07_freeDDict(ZSTDv07_DDict* ddict); |
105 | |
106 | /*! ZSTDv07_decompress_usingDDict() : |
107 | * Decompression using a pre-digested Dictionary |
108 | * Faster startup than ZSTDv07_decompress_usingDict(), recommended when same dictionary is used multiple times. */ |
109 | ZSTDLIBv07_API size_t ZSTDv07_decompress_usingDDict(ZSTDv07_DCtx* dctx, |
110 | void* dst, size_t dstCapacity, |
111 | const void* src, size_t srcSize, |
112 | const ZSTDv07_DDict* ddict); |
113 | |
114 | typedef struct { |
115 | unsigned long long frameContentSize; |
116 | unsigned windowSize; |
117 | unsigned dictID; |
118 | unsigned checksumFlag; |
119 | } ZSTDv07_frameParams; |
120 | |
121 | ZSTDLIBv07_API size_t ZSTDv07_getFrameParams(ZSTDv07_frameParams* fparamsPtr, const void* src, size_t srcSize); /**< doesn't consume input */ |
122 | |
123 | |
124 | |
125 | |
126 | /* ************************************* |
127 | * Streaming functions |
128 | ***************************************/ |
129 | typedef struct ZBUFFv07_DCtx_s ZBUFFv07_DCtx; |
130 | ZSTDLIBv07_API ZBUFFv07_DCtx* ZBUFFv07_createDCtx(void); |
131 | ZSTDLIBv07_API size_t ZBUFFv07_freeDCtx(ZBUFFv07_DCtx* dctx); |
132 | |
133 | ZSTDLIBv07_API size_t ZBUFFv07_decompressInit(ZBUFFv07_DCtx* dctx); |
134 | ZSTDLIBv07_API size_t ZBUFFv07_decompressInitDictionary(ZBUFFv07_DCtx* dctx, const void* dict, size_t dictSize); |
135 | |
136 | ZSTDLIBv07_API size_t ZBUFFv07_decompressContinue(ZBUFFv07_DCtx* dctx, |
137 | void* dst, size_t* dstCapacityPtr, |
138 | const void* src, size_t* srcSizePtr); |
139 | |
140 | /*-*************************************************************************** |
141 | * Streaming decompression howto |
142 | * |
143 | * A ZBUFFv07_DCtx object is required to track streaming operations. |
144 | * Use ZBUFFv07_createDCtx() and ZBUFFv07_freeDCtx() to create/release resources. |
145 | * Use ZBUFFv07_decompressInit() to start a new decompression operation, |
146 | * or ZBUFFv07_decompressInitDictionary() if decompression requires a dictionary. |
147 | * Note that ZBUFFv07_DCtx objects can be re-init multiple times. |
148 | * |
149 | * Use ZBUFFv07_decompressContinue() repetitively to consume your input. |
150 | * *srcSizePtr and *dstCapacityPtr can be any size. |
151 | * The function will report how many bytes were read or written by modifying *srcSizePtr and *dstCapacityPtr. |
152 | * Note that it may not consume the entire input, in which case it's up to the caller to present remaining input again. |
153 | * The content of `dst` will be overwritten (up to *dstCapacityPtr) at each function call, so save its content if it matters, or change `dst`. |
154 | * @return : a hint to preferred nb of bytes to use as input for next function call (it's only a hint, to help latency), |
155 | * or 0 when a frame is completely decoded, |
156 | * or an error code, which can be tested using ZBUFFv07_isError(). |
157 | * |
158 | * Hint : recommended buffer sizes (not compulsory) : ZBUFFv07_recommendedDInSize() and ZBUFFv07_recommendedDOutSize() |
159 | * output : ZBUFFv07_recommendedDOutSize== 128 KB block size is the internal unit, it ensures it's always possible to write a full block when decoded. |
160 | * input : ZBUFFv07_recommendedDInSize == 128KB + 3; |
161 | * just follow indications from ZBUFFv07_decompressContinue() to minimize latency. It should always be <= 128 KB + 3 . |
162 | * *******************************************************************************/ |
163 | |
164 | |
165 | /* ************************************* |
166 | * Tool functions |
167 | ***************************************/ |
168 | ZSTDLIBv07_API unsigned ZBUFFv07_isError(size_t errorCode); |
169 | ZSTDLIBv07_API const char* ZBUFFv07_getErrorName(size_t errorCode); |
170 | |
171 | /** Functions below provide recommended buffer sizes for Compression or Decompression operations. |
172 | * These sizes are just hints, they tend to offer better latency */ |
173 | ZSTDLIBv07_API size_t ZBUFFv07_recommendedDInSize(void); |
174 | ZSTDLIBv07_API size_t ZBUFFv07_recommendedDOutSize(void); |
175 | |
176 | |
177 | /*-************************************* |
178 | * Constants |
179 | ***************************************/ |
180 | #define ZSTDv07_MAGICNUMBER 0xFD2FB527 /* v0.7 */ |
181 | |
182 | |
183 | #if defined (__cplusplus) |
184 | } |
185 | #endif |
186 | |
187 | #endif /* ZSTDv07_H_235446 */ |