| 1 |
/* |
| 2 |
* Copyright (c) 2016-2020, 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_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 */ |