1 | /* |
2 | * Copyright (c) 2016-present, Yann Collet, Facebook, Inc. |
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_getFrameSrcSize() : get the source length of a ZSTD frame |
47 | compressedSize : The size of the 'src' buffer, at least as large as the frame pointed to by 'src' |
48 | return : the number of bytes that would be read to decompress this frame |
49 | or an errorCode if it fails (which can be tested using ZSTDv06_isError()) |
50 | */ |
51 | size_t ZSTDv06_findFrameCompressedSize(const void* src, size_t compressedSize); |
52 | |
53 | /* ************************************* |
54 | * Helper functions |
55 | ***************************************/ |
56 | ZSTDLIBv06_API size_t ZSTDv06_compressBound(size_t srcSize); /*!< maximum compressed size (worst case scenario) */ |
57 | |
58 | /* Error Management */ |
59 | ZSTDLIBv06_API unsigned ZSTDv06_isError(size_t code); /*!< tells if a `size_t` function result is an error code */ |
60 | ZSTDLIBv06_API const char* ZSTDv06_getErrorName(size_t code); /*!< provides readable string for an error code */ |
61 | |
62 | |
63 | /* ************************************* |
64 | * Explicit memory management |
65 | ***************************************/ |
66 | /** Decompression context */ |
67 | typedef struct ZSTDv06_DCtx_s ZSTDv06_DCtx; |
68 | ZSTDLIBv06_API ZSTDv06_DCtx* ZSTDv06_createDCtx(void); |
69 | ZSTDLIBv06_API size_t ZSTDv06_freeDCtx(ZSTDv06_DCtx* dctx); /*!< @return : errorCode */ |
70 | |
71 | /** ZSTDv06_decompressDCtx() : |
72 | * Same as ZSTDv06_decompress(), but requires an already allocated ZSTDv06_DCtx (see ZSTDv06_createDCtx()) */ |
73 | ZSTDLIBv06_API size_t ZSTDv06_decompressDCtx(ZSTDv06_DCtx* ctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize); |
74 | |
75 | |
76 | /*-*********************** |
77 | * Dictionary API |
78 | *************************/ |
79 | /*! ZSTDv06_decompress_usingDict() : |
80 | * Decompression using a pre-defined Dictionary content (see dictBuilder). |
81 | * Dictionary must be identical to the one used during compression, otherwise regenerated data will be corrupted. |
82 | * Note : dict can be NULL, in which case, it's equivalent to ZSTDv06_decompressDCtx() */ |
83 | ZSTDLIBv06_API size_t ZSTDv06_decompress_usingDict(ZSTDv06_DCtx* dctx, |
84 | void* dst, size_t dstCapacity, |
85 | const void* src, size_t srcSize, |
86 | const void* dict,size_t dictSize); |
87 | |
88 | |
89 | /*-************************ |
90 | * Advanced Streaming API |
91 | ***************************/ |
92 | struct ZSTDv06_frameParams_s { unsigned long long frameContentSize; unsigned windowLog; }; |
93 | typedef struct ZSTDv06_frameParams_s ZSTDv06_frameParams; |
94 | |
95 | ZSTDLIBv06_API size_t ZSTDv06_getFrameParams(ZSTDv06_frameParams* fparamsPtr, const void* src, size_t srcSize); /**< doesn't consume input */ |
96 | ZSTDLIBv06_API size_t ZSTDv06_decompressBegin_usingDict(ZSTDv06_DCtx* dctx, const void* dict, size_t dictSize); |
97 | ZSTDLIBv06_API void ZSTDv06_copyDCtx(ZSTDv06_DCtx* dctx, const ZSTDv06_DCtx* preparedDCtx); |
98 | |
99 | ZSTDLIBv06_API size_t ZSTDv06_nextSrcSizeToDecompress(ZSTDv06_DCtx* dctx); |
100 | ZSTDLIBv06_API size_t ZSTDv06_decompressContinue(ZSTDv06_DCtx* dctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize); |
101 | |
102 | |
103 | |
104 | /* ************************************* |
105 | * ZBUFF API |
106 | ***************************************/ |
107 | |
108 | typedef struct ZBUFFv06_DCtx_s ZBUFFv06_DCtx; |
109 | ZSTDLIBv06_API ZBUFFv06_DCtx* ZBUFFv06_createDCtx(void); |
110 | ZSTDLIBv06_API size_t ZBUFFv06_freeDCtx(ZBUFFv06_DCtx* dctx); |
111 | |
112 | ZSTDLIBv06_API size_t ZBUFFv06_decompressInit(ZBUFFv06_DCtx* dctx); |
113 | ZSTDLIBv06_API size_t ZBUFFv06_decompressInitDictionary(ZBUFFv06_DCtx* dctx, const void* dict, size_t dictSize); |
114 | |
115 | ZSTDLIBv06_API size_t ZBUFFv06_decompressContinue(ZBUFFv06_DCtx* dctx, |
116 | void* dst, size_t* dstCapacityPtr, |
117 | const void* src, size_t* srcSizePtr); |
118 | |
119 | /*-*************************************************************************** |
120 | * Streaming decompression howto |
121 | * |
122 | * A ZBUFFv06_DCtx object is required to track streaming operations. |
123 | * Use ZBUFFv06_createDCtx() and ZBUFFv06_freeDCtx() to create/release resources. |
124 | * Use ZBUFFv06_decompressInit() to start a new decompression operation, |
125 | * or ZBUFFv06_decompressInitDictionary() if decompression requires a dictionary. |
126 | * Note that ZBUFFv06_DCtx objects can be re-init multiple times. |
127 | * |
128 | * Use ZBUFFv06_decompressContinue() repetitively to consume your input. |
129 | * *srcSizePtr and *dstCapacityPtr can be any size. |
130 | * The function will report how many bytes were read or written by modifying *srcSizePtr and *dstCapacityPtr. |
131 | * Note that it may not consume the entire input, in which case it's up to the caller to present remaining input again. |
132 | * The content of `dst` will be overwritten (up to *dstCapacityPtr) at each function call, so save its content if it matters, or change `dst`. |
133 | * @return : a hint to preferred nb of bytes to use as input for next function call (it's only a hint, to help latency), |
134 | * or 0 when a frame is completely decoded, |
135 | * or an error code, which can be tested using ZBUFFv06_isError(). |
136 | * |
137 | * Hint : recommended buffer sizes (not compulsory) : ZBUFFv06_recommendedDInSize() and ZBUFFv06_recommendedDOutSize() |
138 | * output : ZBUFFv06_recommendedDOutSize== 128 KB block size is the internal unit, it ensures it's always possible to write a full block when decoded. |
139 | * input : ZBUFFv06_recommendedDInSize == 128KB + 3; |
140 | * just follow indications from ZBUFFv06_decompressContinue() to minimize latency. It should always be <= 128 KB + 3 . |
141 | * *******************************************************************************/ |
142 | |
143 | |
144 | /* ************************************* |
145 | * Tool functions |
146 | ***************************************/ |
147 | ZSTDLIBv06_API unsigned ZBUFFv06_isError(size_t errorCode); |
148 | ZSTDLIBv06_API const char* ZBUFFv06_getErrorName(size_t errorCode); |
149 | |
150 | /** Functions below provide recommended buffer sizes for Compression or Decompression operations. |
151 | * These sizes are just hints, they tend to offer better latency */ |
152 | ZSTDLIBv06_API size_t ZBUFFv06_recommendedDInSize(void); |
153 | ZSTDLIBv06_API size_t ZBUFFv06_recommendedDOutSize(void); |
154 | |
155 | |
156 | /*-************************************* |
157 | * Constants |
158 | ***************************************/ |
159 | #define ZSTDv06_MAGICNUMBER 0xFD2FB526 /* v0.6 */ |
160 | |
161 | |
162 | |
163 | #if defined (__cplusplus) |
164 | } |
165 | #endif |
166 | |
167 | #endif /* ZSTDv06_BUFFERED_H */ |
168 | |