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