| 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 ZSTDv05_H |
| 12 |
#define ZSTDv05_H |
| 13 |
|
| 14 |
#if defined (__cplusplus) |
| 15 |
extern "C" { |
| 16 |
#endif |
| 17 |
|
| 18 |
/*-************************************* |
| 19 |
* Dependencies |
| 20 |
***************************************/ |
| 21 |
#include <stddef.h> /* size_t */ |
| 22 |
#include "../common/mem.h" /* U64, U32 */ |
| 23 |
|
| 24 |
|
| 25 |
/* ************************************* |
| 26 |
* Simple functions |
| 27 |
***************************************/ |
| 28 |
/*! ZSTDv05_decompress() : |
| 29 |
`compressedSize` : is the _exact_ size of the compressed blob, otherwise decompression will fail. |
| 30 |
`dstCapacity` must be large enough, equal or larger than originalSize. |
| 31 |
@return : the number of bytes decompressed into `dst` (<= `dstCapacity`), |
| 32 |
or an errorCode if it fails (which can be tested using ZSTDv05_isError()) */ |
| 33 |
size_t ZSTDv05_decompress( void* dst, size_t dstCapacity, |
| 34 |
const void* src, size_t compressedSize); |
| 35 |
|
| 36 |
/** |
| 37 |
ZSTDv05_findFrameSizeInfoLegacy() : get the source length and decompressed bound of a ZSTD frame compliant with v0.5.x format |
| 38 |
srcSize : The size of the 'src' buffer, at least as large as the frame pointed to by 'src' |
| 39 |
cSize (output parameter) : the number of bytes that would be read to decompress this frame |
| 40 |
or an error code if it fails (which can be tested using ZSTDv01_isError()) |
| 41 |
dBound (output parameter) : an upper-bound for the decompressed size of the data in the frame |
| 42 |
or ZSTD_CONTENTSIZE_ERROR if an error occurs |
| 43 |
|
| 44 |
note : assumes `cSize` and `dBound` are _not_ NULL. |
| 45 |
*/ |
| 46 |
void ZSTDv05_findFrameSizeInfoLegacy(const void *src, size_t srcSize, |
| 47 |
size_t* cSize, unsigned long long* dBound); |
| 48 |
|
| 49 |
/* ************************************* |
| 50 |
* Helper functions |
| 51 |
***************************************/ |
| 52 |
/* Error Management */ |
| 53 |
unsigned ZSTDv05_isError(size_t code); /*!< tells if a `size_t` function result is an error code */ |
| 54 |
const char* ZSTDv05_getErrorName(size_t code); /*!< provides readable string for an error code */ |
| 55 |
|
| 56 |
|
| 57 |
/* ************************************* |
| 58 |
* Explicit memory management |
| 59 |
***************************************/ |
| 60 |
/** Decompression context */ |
| 61 |
typedef struct ZSTDv05_DCtx_s ZSTDv05_DCtx; |
| 62 |
ZSTDv05_DCtx* ZSTDv05_createDCtx(void); |
| 63 |
size_t ZSTDv05_freeDCtx(ZSTDv05_DCtx* dctx); /*!< @return : errorCode */ |
| 64 |
|
| 65 |
/** ZSTDv05_decompressDCtx() : |
| 66 |
* Same as ZSTDv05_decompress(), but requires an already allocated ZSTDv05_DCtx (see ZSTDv05_createDCtx()) */ |
| 67 |
size_t ZSTDv05_decompressDCtx(ZSTDv05_DCtx* ctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize); |
| 68 |
|
| 69 |
|
| 70 |
/*-*********************** |
| 71 |
* Simple Dictionary API |
| 72 |
*************************/ |
| 73 |
/*! ZSTDv05_decompress_usingDict() : |
| 74 |
* Decompression using a pre-defined Dictionary content (see dictBuilder). |
| 75 |
* Dictionary must be identical to the one used during compression, otherwise regenerated data will be corrupted. |
| 76 |
* Note : dict can be NULL, in which case, it's equivalent to ZSTDv05_decompressDCtx() */ |
| 77 |
size_t ZSTDv05_decompress_usingDict(ZSTDv05_DCtx* dctx, |
| 78 |
void* dst, size_t dstCapacity, |
| 79 |
const void* src, size_t srcSize, |
| 80 |
const void* dict,size_t dictSize); |
| 81 |
|
| 82 |
/*-************************ |
| 83 |
* Advanced Streaming API |
| 84 |
***************************/ |
| 85 |
typedef enum { ZSTDv05_fast, ZSTDv05_greedy, ZSTDv05_lazy, ZSTDv05_lazy2, ZSTDv05_btlazy2, ZSTDv05_opt, ZSTDv05_btopt } ZSTDv05_strategy; |
| 86 |
typedef struct { |
| 87 |
U64 srcSize; |
| 88 |
U32 windowLog; /* the only useful information to retrieve */ |
| 89 |
U32 contentLog; U32 hashLog; U32 searchLog; U32 searchLength; U32 targetLength; ZSTDv05_strategy strategy; |
| 90 |
} ZSTDv05_parameters; |
| 91 |
size_t ZSTDv05_getFrameParams(ZSTDv05_parameters* params, const void* src, size_t srcSize); |
| 92 |
|
| 93 |
size_t ZSTDv05_decompressBegin_usingDict(ZSTDv05_DCtx* dctx, const void* dict, size_t dictSize); |
| 94 |
void ZSTDv05_copyDCtx(ZSTDv05_DCtx* dstDCtx, const ZSTDv05_DCtx* srcDCtx); |
| 95 |
size_t ZSTDv05_nextSrcSizeToDecompress(ZSTDv05_DCtx* dctx); |
| 96 |
size_t ZSTDv05_decompressContinue(ZSTDv05_DCtx* dctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize); |
| 97 |
|
| 98 |
|
| 99 |
/*-*********************** |
| 100 |
* ZBUFF API |
| 101 |
*************************/ |
| 102 |
typedef struct ZBUFFv05_DCtx_s ZBUFFv05_DCtx; |
| 103 |
ZBUFFv05_DCtx* ZBUFFv05_createDCtx(void); |
| 104 |
size_t ZBUFFv05_freeDCtx(ZBUFFv05_DCtx* dctx); |
| 105 |
|
| 106 |
size_t ZBUFFv05_decompressInit(ZBUFFv05_DCtx* dctx); |
| 107 |
size_t ZBUFFv05_decompressInitDictionary(ZBUFFv05_DCtx* dctx, const void* dict, size_t dictSize); |
| 108 |
|
| 109 |
size_t ZBUFFv05_decompressContinue(ZBUFFv05_DCtx* dctx, |
| 110 |
void* dst, size_t* dstCapacityPtr, |
| 111 |
const void* src, size_t* srcSizePtr); |
| 112 |
|
| 113 |
/*-*************************************************************************** |
| 114 |
* Streaming decompression |
| 115 |
* |
| 116 |
* A ZBUFFv05_DCtx object is required to track streaming operations. |
| 117 |
* Use ZBUFFv05_createDCtx() and ZBUFFv05_freeDCtx() to create/release resources. |
| 118 |
* Use ZBUFFv05_decompressInit() to start a new decompression operation, |
| 119 |
* or ZBUFFv05_decompressInitDictionary() if decompression requires a dictionary. |
| 120 |
* Note that ZBUFFv05_DCtx objects can be reused multiple times. |
| 121 |
* |
| 122 |
* Use ZBUFFv05_decompressContinue() repetitively to consume your input. |
| 123 |
* *srcSizePtr and *dstCapacityPtr can be any size. |
| 124 |
* The function will report how many bytes were read or written by modifying *srcSizePtr and *dstCapacityPtr. |
| 125 |
* Note that it may not consume the entire input, in which case it's up to the caller to present remaining input again. |
| 126 |
* The content of @dst will be overwritten (up to *dstCapacityPtr) at each function call, so save its content if it matters or change @dst. |
| 127 |
* @return : a hint to preferred nb of bytes to use as input for next function call (it's only a hint, to help latency) |
| 128 |
* or 0 when a frame is completely decoded |
| 129 |
* or an error code, which can be tested using ZBUFFv05_isError(). |
| 130 |
* |
| 131 |
* Hint : recommended buffer sizes (not compulsory) : ZBUFFv05_recommendedDInSize() / ZBUFFv05_recommendedDOutSize() |
| 132 |
* output : ZBUFFv05_recommendedDOutSize==128 KB block size is the internal unit, it ensures it's always possible to write a full block when decoded. |
| 133 |
* input : ZBUFFv05_recommendedDInSize==128Kb+3; just follow indications from ZBUFFv05_decompressContinue() to minimize latency. It should always be <= 128 KB + 3 . |
| 134 |
* *******************************************************************************/ |
| 135 |
|
| 136 |
|
| 137 |
/* ************************************* |
| 138 |
* Tool functions |
| 139 |
***************************************/ |
| 140 |
unsigned ZBUFFv05_isError(size_t errorCode); |
| 141 |
const char* ZBUFFv05_getErrorName(size_t errorCode); |
| 142 |
|
| 143 |
/** Functions below provide recommended buffer sizes for Compression or Decompression operations. |
| 144 |
* These sizes are just hints, and tend to offer better latency */ |
| 145 |
size_t ZBUFFv05_recommendedDInSize(void); |
| 146 |
size_t ZBUFFv05_recommendedDOutSize(void); |
| 147 |
|
| 148 |
|
| 149 |
|
| 150 |
/*-************************************* |
| 151 |
* Constants |
| 152 |
***************************************/ |
| 153 |
#define ZSTDv05_MAGICNUMBER 0xFD2FB525 /* v0.5 */ |
| 154 |
|
| 155 |
|
| 156 |
|
| 157 |
|
| 158 |
#if defined (__cplusplus) |
| 159 |
} |
| 160 |
#endif |
| 161 |
|
| 162 |
#endif /* ZSTDv0505_H */ |