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 ZSTD_V04_H_91868324769238 12 #define ZSTD_V04_H_91868324769238 13 14 #if defined (__cplusplus) 15 extern "C" { 16 #endif 17 18 /* ************************************* 19 * Includes 20 ***************************************/ 21 #include <stddef.h> /* size_t */ 22 23 24 /* ************************************* 25 * Simple one-step function 26 ***************************************/ 27 /** 28 ZSTDv04_decompress() : decompress ZSTD frames compliant with v0.4.x format 29 compressedSize : is the exact source size 30 maxOriginalSize : is the size of the 'dst' buffer, which must be already allocated. 31 It must be equal or larger than originalSize, otherwise decompression will fail. 32 return : the number of bytes decompressed into destination buffer (originalSize) 33 or an errorCode if it fails (which can be tested using ZSTDv01_isError()) 34 */ 35 size_t ZSTDv04_decompress( void* dst, size_t maxOriginalSize, 36 const void* src, size_t compressedSize); 37 38 /** 39 ZSTDv04_findFrameSizeInfoLegacy() : get the source length and decompressed bound of a ZSTD frame compliant with v0.4.x format 40 srcSize : The size of the 'src' buffer, at least as large as the frame pointed to by 'src' 41 cSize (output parameter) : the number of bytes that would be read to decompress this frame 42 or an error code if it fails (which can be tested using ZSTDv01_isError()) 43 dBound (output parameter) : an upper-bound for the decompressed size of the data in the frame 44 or ZSTD_CONTENTSIZE_ERROR if an error occurs 45 46 note : assumes `cSize` and `dBound` are _not_ NULL. 47 */ 48 void ZSTDv04_findFrameSizeInfoLegacy(const void *src, size_t srcSize, 49 size_t* cSize, unsigned long long* dBound); 50 51 /** 52 ZSTDv04_isError() : tells if the result of ZSTDv04_decompress() is an error 53 */ 54 unsigned ZSTDv04_isError(size_t code); 55 56 57 /* ************************************* 58 * Advanced functions 59 ***************************************/ 60 typedef struct ZSTDv04_Dctx_s ZSTDv04_Dctx; 61 ZSTDv04_Dctx* ZSTDv04_createDCtx(void); 62 size_t ZSTDv04_freeDCtx(ZSTDv04_Dctx* dctx); 63 64 size_t ZSTDv04_decompressDCtx(ZSTDv04_Dctx* dctx, 65 void* dst, size_t maxOriginalSize, 66 const void* src, size_t compressedSize); 67 68 69 /* ************************************* 70 * Direct Streaming 71 ***************************************/ 72 size_t ZSTDv04_resetDCtx(ZSTDv04_Dctx* dctx); 73 74 size_t ZSTDv04_nextSrcSizeToDecompress(ZSTDv04_Dctx* dctx); 75 size_t ZSTDv04_decompressContinue(ZSTDv04_Dctx* dctx, void* dst, size_t maxDstSize, const void* src, size_t srcSize); 76 /** 77 Use above functions alternatively. 78 ZSTD_nextSrcSizeToDecompress() tells how much bytes to provide as 'srcSize' to ZSTD_decompressContinue(). 79 ZSTD_decompressContinue() will use previous data blocks to improve compression if they are located prior to current block. 80 Result is the number of bytes regenerated within 'dst'. 81 It can be zero, which is not an error; it just means ZSTD_decompressContinue() has decoded some header. 82 */ 83 84 85 /* ************************************* 86 * Buffered Streaming 87 ***************************************/ 88 typedef struct ZBUFFv04_DCtx_s ZBUFFv04_DCtx; 89 ZBUFFv04_DCtx* ZBUFFv04_createDCtx(void); 90 size_t ZBUFFv04_freeDCtx(ZBUFFv04_DCtx* dctx); 91 92 size_t ZBUFFv04_decompressInit(ZBUFFv04_DCtx* dctx); 93 size_t ZBUFFv04_decompressWithDictionary(ZBUFFv04_DCtx* dctx, const void* dict, size_t dictSize); 94 95 size_t ZBUFFv04_decompressContinue(ZBUFFv04_DCtx* dctx, void* dst, size_t* maxDstSizePtr, const void* src, size_t* srcSizePtr); 96 97 /** ************************************************ 98 * Streaming decompression 99 * 100 * A ZBUFF_DCtx object is required to track streaming operation. 101 * Use ZBUFF_createDCtx() and ZBUFF_freeDCtx() to create/release resources. 102 * Use ZBUFF_decompressInit() to start a new decompression operation. 103 * ZBUFF_DCtx objects can be reused multiple times. 104 * 105 * Optionally, a reference to a static dictionary can be set, using ZBUFF_decompressWithDictionary() 106 * It must be the same content as the one set during compression phase. 107 * Dictionary content must remain accessible during the decompression process. 108 * 109 * Use ZBUFF_decompressContinue() repetitively to consume your input. 110 * *srcSizePtr and *maxDstSizePtr can be any size. 111 * The function will report how many bytes were read or written by modifying *srcSizePtr and *maxDstSizePtr. 112 * Note that it may not consume the entire input, in which case it's up to the caller to present remaining input again. 113 * The content of dst will be overwritten (up to *maxDstSizePtr) at each function call, so save its content if it matters or change dst. 114 * @return : a hint to preferred nb of bytes to use as input for next function call (it's only a hint, to improve latency) 115 * or 0 when a frame is completely decoded 116 * or an error code, which can be tested using ZBUFF_isError(). 117 * 118 * Hint : recommended buffer sizes (not compulsory) : ZBUFF_recommendedDInSize / ZBUFF_recommendedDOutSize 119 * output : ZBUFF_recommendedDOutSize==128 KB block size is the internal unit, it ensures it's always possible to write a full block when it's decoded. 120 * input : ZBUFF_recommendedDInSize==128Kb+3; just follow indications from ZBUFF_decompressContinue() to minimize latency. It should always be <= 128 KB + 3 . 121 * **************************************************/ 122 unsigned ZBUFFv04_isError(size_t errorCode); 123 const char* ZBUFFv04_getErrorName(size_t errorCode); 124 125 126 /** The below functions provide recommended buffer sizes for Compression or Decompression operations. 127 * These sizes are not compulsory, they just tend to offer better latency */ 128 size_t ZBUFFv04_recommendedDInSize(void); 129 size_t ZBUFFv04_recommendedDOutSize(void); 130 131 132 /* ************************************* 133 * Prefix - version detection 134 ***************************************/ 135 #define ZSTDv04_magicNumber 0xFD2FB524 /* v0.4 */ 136 137 138 #if defined (__cplusplus) 139 } 140 #endif 141 142 #endif /* ZSTD_V04_H_91868324769238 */ 143