| 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 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 */ |