1*27162e4eSAndroid Build Coastguard Worker<html> 2*27162e4eSAndroid Build Coastguard Worker<head> 3*27162e4eSAndroid Build Coastguard Worker<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 4*27162e4eSAndroid Build Coastguard Worker<title>1.10.0 Manual</title> 5*27162e4eSAndroid Build Coastguard Worker</head> 6*27162e4eSAndroid Build Coastguard Worker<body> 7*27162e4eSAndroid Build Coastguard Worker<h1>1.10.0 Manual</h1> 8*27162e4eSAndroid Build Coastguard Worker<hr> 9*27162e4eSAndroid Build Coastguard Worker<a name="Contents"></a><h2>Contents</h2> 10*27162e4eSAndroid Build Coastguard Worker<ol> 11*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter1">Introduction</a></li> 12*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter2">Compiler specifics</a></li> 13*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter3">Error management</a></li> 14*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter4">Frame compression types</a></li> 15*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter5">Simple compression function</a></li> 16*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter6">Advanced compression functions</a></li> 17*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter7">Resource Management</a></li> 18*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter8">Compression</a></li> 19*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter9">Decompression functions</a></li> 20*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter10">Streaming decompression functions</a></li> 21*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter11">Dictionary compression API</a></li> 22*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter12">Bulk processing dictionary compression</a></li> 23*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter13">Advanced compression operations</a></li> 24*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter14">Custom memory allocation</a></li> 25*27162e4eSAndroid Build Coastguard Worker</ol> 26*27162e4eSAndroid Build Coastguard Worker<hr> 27*27162e4eSAndroid Build Coastguard Worker<a name="Chapter1"></a><h2>Introduction</h2><pre> 28*27162e4eSAndroid Build Coastguard Worker lz4frame.h implements LZ4 frame specification: see doc/lz4_Frame_format.md . 29*27162e4eSAndroid Build Coastguard Worker LZ4 Frames are compatible with `lz4` CLI, 30*27162e4eSAndroid Build Coastguard Worker and designed to be interoperable with any system. 31*27162e4eSAndroid Build Coastguard Worker<BR></pre> 32*27162e4eSAndroid Build Coastguard Worker 33*27162e4eSAndroid Build Coastguard Worker<a name="Chapter2"></a><h2>Compiler specifics</h2><pre></pre> 34*27162e4eSAndroid Build Coastguard Worker 35*27162e4eSAndroid Build Coastguard Worker<a name="Chapter3"></a><h2>Error management</h2><pre></pre> 36*27162e4eSAndroid Build Coastguard Worker 37*27162e4eSAndroid Build Coastguard Worker<pre><b>unsigned LZ4F_isError(LZ4F_errorCode_t code); </b>/**< tells when a function result is an error code */<b> 38*27162e4eSAndroid Build Coastguard Worker</b></pre><BR> 39*27162e4eSAndroid Build Coastguard Worker<pre><b>const char* LZ4F_getErrorName(LZ4F_errorCode_t code); </b>/**< return error code string; for debugging */<b> 40*27162e4eSAndroid Build Coastguard Worker</b></pre><BR> 41*27162e4eSAndroid Build Coastguard Worker<a name="Chapter4"></a><h2>Frame compression types</h2><pre> 42*27162e4eSAndroid Build Coastguard Worker<BR></pre> 43*27162e4eSAndroid Build Coastguard Worker 44*27162e4eSAndroid Build Coastguard Worker<pre><b>typedef enum { 45*27162e4eSAndroid Build Coastguard Worker LZ4F_default=0, 46*27162e4eSAndroid Build Coastguard Worker LZ4F_max64KB=4, 47*27162e4eSAndroid Build Coastguard Worker LZ4F_max256KB=5, 48*27162e4eSAndroid Build Coastguard Worker LZ4F_max1MB=6, 49*27162e4eSAndroid Build Coastguard Worker LZ4F_max4MB=7 50*27162e4eSAndroid Build Coastguard Worker LZ4F_OBSOLETE_ENUM(max64KB) 51*27162e4eSAndroid Build Coastguard Worker LZ4F_OBSOLETE_ENUM(max256KB) 52*27162e4eSAndroid Build Coastguard Worker LZ4F_OBSOLETE_ENUM(max1MB) 53*27162e4eSAndroid Build Coastguard Worker LZ4F_OBSOLETE_ENUM(max4MB) 54*27162e4eSAndroid Build Coastguard Worker} LZ4F_blockSizeID_t; 55*27162e4eSAndroid Build Coastguard Worker</b></pre><BR> 56*27162e4eSAndroid Build Coastguard Worker<pre><b>typedef enum { 57*27162e4eSAndroid Build Coastguard Worker LZ4F_blockLinked=0, 58*27162e4eSAndroid Build Coastguard Worker LZ4F_blockIndependent 59*27162e4eSAndroid Build Coastguard Worker LZ4F_OBSOLETE_ENUM(blockLinked) 60*27162e4eSAndroid Build Coastguard Worker LZ4F_OBSOLETE_ENUM(blockIndependent) 61*27162e4eSAndroid Build Coastguard Worker} LZ4F_blockMode_t; 62*27162e4eSAndroid Build Coastguard Worker</b></pre><BR> 63*27162e4eSAndroid Build Coastguard Worker<pre><b>typedef enum { 64*27162e4eSAndroid Build Coastguard Worker LZ4F_noContentChecksum=0, 65*27162e4eSAndroid Build Coastguard Worker LZ4F_contentChecksumEnabled 66*27162e4eSAndroid Build Coastguard Worker LZ4F_OBSOLETE_ENUM(noContentChecksum) 67*27162e4eSAndroid Build Coastguard Worker LZ4F_OBSOLETE_ENUM(contentChecksumEnabled) 68*27162e4eSAndroid Build Coastguard Worker} LZ4F_contentChecksum_t; 69*27162e4eSAndroid Build Coastguard Worker</b></pre><BR> 70*27162e4eSAndroid Build Coastguard Worker<pre><b>typedef enum { 71*27162e4eSAndroid Build Coastguard Worker LZ4F_noBlockChecksum=0, 72*27162e4eSAndroid Build Coastguard Worker LZ4F_blockChecksumEnabled 73*27162e4eSAndroid Build Coastguard Worker} LZ4F_blockChecksum_t; 74*27162e4eSAndroid Build Coastguard Worker</b></pre><BR> 75*27162e4eSAndroid Build Coastguard Worker<pre><b>typedef enum { 76*27162e4eSAndroid Build Coastguard Worker LZ4F_frame=0, 77*27162e4eSAndroid Build Coastguard Worker LZ4F_skippableFrame 78*27162e4eSAndroid Build Coastguard Worker LZ4F_OBSOLETE_ENUM(skippableFrame) 79*27162e4eSAndroid Build Coastguard Worker} LZ4F_frameType_t; 80*27162e4eSAndroid Build Coastguard Worker</b></pre><BR> 81*27162e4eSAndroid Build Coastguard Worker<pre><b>typedef struct { 82*27162e4eSAndroid Build Coastguard Worker LZ4F_blockSizeID_t blockSizeID; </b>/* max64KB, max256KB, max1MB, max4MB; 0 == default (LZ4F_max64KB) */<b> 83*27162e4eSAndroid Build Coastguard Worker LZ4F_blockMode_t blockMode; </b>/* LZ4F_blockLinked, LZ4F_blockIndependent; 0 == default (LZ4F_blockLinked) */<b> 84*27162e4eSAndroid Build Coastguard Worker LZ4F_contentChecksum_t contentChecksumFlag; </b>/* 1: add a 32-bit checksum of frame's decompressed data; 0 == default (disabled) */<b> 85*27162e4eSAndroid Build Coastguard Worker LZ4F_frameType_t frameType; </b>/* read-only field : LZ4F_frame or LZ4F_skippableFrame */<b> 86*27162e4eSAndroid Build Coastguard Worker unsigned long long contentSize; </b>/* Size of uncompressed content ; 0 == unknown */<b> 87*27162e4eSAndroid Build Coastguard Worker unsigned dictID; </b>/* Dictionary ID, sent by compressor to help decoder select correct dictionary; 0 == no dictID provided */<b> 88*27162e4eSAndroid Build Coastguard Worker LZ4F_blockChecksum_t blockChecksumFlag; </b>/* 1: each block followed by a checksum of block's compressed data; 0 == default (disabled) */<b> 89*27162e4eSAndroid Build Coastguard Worker} LZ4F_frameInfo_t; 90*27162e4eSAndroid Build Coastguard Worker</b><p> makes it possible to set or read frame parameters. 91*27162e4eSAndroid Build Coastguard Worker Structure must be first init to 0, using memset() or LZ4F_INIT_FRAMEINFO, 92*27162e4eSAndroid Build Coastguard Worker setting all parameters to default. 93*27162e4eSAndroid Build Coastguard Worker It's then possible to update selectively some parameters 94*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 95*27162e4eSAndroid Build Coastguard Worker 96*27162e4eSAndroid Build Coastguard Worker<pre><b>typedef struct { 97*27162e4eSAndroid Build Coastguard Worker LZ4F_frameInfo_t frameInfo; 98*27162e4eSAndroid Build Coastguard Worker int compressionLevel; </b>/* 0: default (fast mode); values > LZ4HC_CLEVEL_MAX count as LZ4HC_CLEVEL_MAX; values < 0 trigger "fast acceleration" */<b> 99*27162e4eSAndroid Build Coastguard Worker unsigned autoFlush; </b>/* 1: always flush; reduces usage of internal buffers */<b> 100*27162e4eSAndroid Build Coastguard Worker unsigned favorDecSpeed; </b>/* 1: parser favors decompression speed vs compression ratio. Only works for high compression modes (>= LZ4HC_CLEVEL_OPT_MIN) */ /* v1.8.2+ */<b> 101*27162e4eSAndroid Build Coastguard Worker unsigned reserved[3]; </b>/* must be zero for forward compatibility */<b> 102*27162e4eSAndroid Build Coastguard Worker} LZ4F_preferences_t; 103*27162e4eSAndroid Build Coastguard Worker</b><p> makes it possible to supply advanced compression instructions to streaming interface. 104*27162e4eSAndroid Build Coastguard Worker Structure must be first init to 0, using memset() or LZ4F_INIT_PREFERENCES, 105*27162e4eSAndroid Build Coastguard Worker setting all parameters to default. 106*27162e4eSAndroid Build Coastguard Worker All reserved fields must be set to zero. 107*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 108*27162e4eSAndroid Build Coastguard Worker 109*27162e4eSAndroid Build Coastguard Worker<a name="Chapter5"></a><h2>Simple compression function</h2><pre></pre> 110*27162e4eSAndroid Build Coastguard Worker 111*27162e4eSAndroid Build Coastguard Worker<pre><b>size_t LZ4F_compressFrame(void* dstBuffer, size_t dstCapacity, 112*27162e4eSAndroid Build Coastguard Worker const void* srcBuffer, size_t srcSize, 113*27162e4eSAndroid Build Coastguard Worker const LZ4F_preferences_t* preferencesPtr); 114*27162e4eSAndroid Build Coastguard Worker</b><p> Compress srcBuffer content into an LZ4-compressed frame. 115*27162e4eSAndroid Build Coastguard Worker It's a one shot operation, all input content is consumed, and all output is generated. 116*27162e4eSAndroid Build Coastguard Worker 117*27162e4eSAndroid Build Coastguard Worker Note : it's a stateless operation (no LZ4F_cctx state needed). 118*27162e4eSAndroid Build Coastguard Worker In order to reduce load on the allocator, LZ4F_compressFrame(), by default, 119*27162e4eSAndroid Build Coastguard Worker uses the stack to allocate space for the compression state and some table. 120*27162e4eSAndroid Build Coastguard Worker If this usage of the stack is too much for your application, 121*27162e4eSAndroid Build Coastguard Worker consider compiling `lz4frame.c` with compile-time macro LZ4F_HEAPMODE set to 1 instead. 122*27162e4eSAndroid Build Coastguard Worker All state allocations will use the Heap. 123*27162e4eSAndroid Build Coastguard Worker It also means each invocation of LZ4F_compressFrame() will trigger several internal alloc/free invocations. 124*27162e4eSAndroid Build Coastguard Worker 125*27162e4eSAndroid Build Coastguard Worker @dstCapacity MUST be >= LZ4F_compressFrameBound(srcSize, preferencesPtr). 126*27162e4eSAndroid Build Coastguard Worker @preferencesPtr is optional : one can provide NULL, in which case all preferences are set to default. 127*27162e4eSAndroid Build Coastguard Worker @return : number of bytes written into dstBuffer. 128*27162e4eSAndroid Build Coastguard Worker or an error code if it fails (can be tested using LZ4F_isError()) 129*27162e4eSAndroid Build Coastguard Worker 130*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 131*27162e4eSAndroid Build Coastguard Worker 132*27162e4eSAndroid Build Coastguard Worker<pre><b>size_t LZ4F_compressFrameBound(size_t srcSize, const LZ4F_preferences_t* preferencesPtr); 133*27162e4eSAndroid Build Coastguard Worker</b><p> Returns the maximum possible compressed size with LZ4F_compressFrame() given srcSize and preferences. 134*27162e4eSAndroid Build Coastguard Worker `preferencesPtr` is optional. It can be replaced by NULL, in which case, the function will assume default preferences. 135*27162e4eSAndroid Build Coastguard Worker Note : this result is only usable with LZ4F_compressFrame(). 136*27162e4eSAndroid Build Coastguard Worker It may also be relevant to LZ4F_compressUpdate() _only if_ no flush() operation is ever performed. 137*27162e4eSAndroid Build Coastguard Worker 138*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 139*27162e4eSAndroid Build Coastguard Worker 140*27162e4eSAndroid Build Coastguard Worker<pre><b>int LZ4F_compressionLevel_max(void); </b>/* v1.8.0+ */<b> 141*27162e4eSAndroid Build Coastguard Worker</b><p> @return maximum allowed compression level (currently: 12) 142*27162e4eSAndroid Build Coastguard Worker 143*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 144*27162e4eSAndroid Build Coastguard Worker 145*27162e4eSAndroid Build Coastguard Worker<a name="Chapter6"></a><h2>Advanced compression functions</h2><pre></pre> 146*27162e4eSAndroid Build Coastguard Worker 147*27162e4eSAndroid Build Coastguard Worker<pre><b>typedef struct { 148*27162e4eSAndroid Build Coastguard Worker unsigned stableSrc; </b>/* 1 == src content will remain present on future calls to LZ4F_compress(); skip copying src content within tmp buffer */<b> 149*27162e4eSAndroid Build Coastguard Worker unsigned reserved[3]; 150*27162e4eSAndroid Build Coastguard Worker} LZ4F_compressOptions_t; 151*27162e4eSAndroid Build Coastguard Worker</b></pre><BR> 152*27162e4eSAndroid Build Coastguard Worker<a name="Chapter7"></a><h2>Resource Management</h2><pre></pre> 153*27162e4eSAndroid Build Coastguard Worker 154*27162e4eSAndroid Build Coastguard Worker<pre><b>LZ4F_errorCode_t LZ4F_createCompressionContext(LZ4F_cctx** cctxPtr, unsigned version); 155*27162e4eSAndroid Build Coastguard WorkerLZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx); 156*27162e4eSAndroid Build Coastguard Worker</b><p> The first thing to do is to create a compressionContext object, 157*27162e4eSAndroid Build Coastguard Worker which will keep track of operation state during streaming compression. 158*27162e4eSAndroid Build Coastguard Worker This is achieved using LZ4F_createCompressionContext(), which takes as argument a version, 159*27162e4eSAndroid Build Coastguard Worker and a pointer to LZ4F_cctx*, to write the resulting pointer into. 160*27162e4eSAndroid Build Coastguard Worker @version provided MUST be LZ4F_VERSION. It is intended to track potential version mismatch, notably when using DLL. 161*27162e4eSAndroid Build Coastguard Worker The function provides a pointer to a fully allocated LZ4F_cctx object. 162*27162e4eSAndroid Build Coastguard Worker @cctxPtr MUST be != NULL. 163*27162e4eSAndroid Build Coastguard Worker If @return != zero, context creation failed. 164*27162e4eSAndroid Build Coastguard Worker A created compression context can be employed multiple times for consecutive streaming operations. 165*27162e4eSAndroid Build Coastguard Worker Once all streaming compression jobs are completed, 166*27162e4eSAndroid Build Coastguard Worker the state object can be released using LZ4F_freeCompressionContext(). 167*27162e4eSAndroid Build Coastguard Worker Note1 : LZ4F_freeCompressionContext() is always successful. Its return value can be ignored. 168*27162e4eSAndroid Build Coastguard Worker Note2 : LZ4F_freeCompressionContext() works fine with NULL input pointers (do nothing). 169*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 170*27162e4eSAndroid Build Coastguard Worker 171*27162e4eSAndroid Build Coastguard Worker<a name="Chapter8"></a><h2>Compression</h2><pre></pre> 172*27162e4eSAndroid Build Coastguard Worker 173*27162e4eSAndroid Build Coastguard Worker<pre><b>size_t LZ4F_compressBegin(LZ4F_cctx* cctx, 174*27162e4eSAndroid Build Coastguard Worker void* dstBuffer, size_t dstCapacity, 175*27162e4eSAndroid Build Coastguard Worker const LZ4F_preferences_t* prefsPtr); 176*27162e4eSAndroid Build Coastguard Worker</b><p> will write the frame header into dstBuffer. 177*27162e4eSAndroid Build Coastguard Worker dstCapacity must be >= LZ4F_HEADER_SIZE_MAX bytes. 178*27162e4eSAndroid Build Coastguard Worker `prefsPtr` is optional : NULL can be provided to set all preferences to default. 179*27162e4eSAndroid Build Coastguard Worker @return : number of bytes written into dstBuffer for the header 180*27162e4eSAndroid Build Coastguard Worker or an error code (which can be tested using LZ4F_isError()) 181*27162e4eSAndroid Build Coastguard Worker 182*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 183*27162e4eSAndroid Build Coastguard Worker 184*27162e4eSAndroid Build Coastguard Worker<pre><b>size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr); 185*27162e4eSAndroid Build Coastguard Worker</b><p> Provides minimum dstCapacity required to guarantee success of 186*27162e4eSAndroid Build Coastguard Worker LZ4F_compressUpdate(), given a srcSize and preferences, for a worst case scenario. 187*27162e4eSAndroid Build Coastguard Worker When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() instead. 188*27162e4eSAndroid Build Coastguard Worker Note that the result is only valid for a single invocation of LZ4F_compressUpdate(). 189*27162e4eSAndroid Build Coastguard Worker When invoking LZ4F_compressUpdate() multiple times, 190*27162e4eSAndroid Build Coastguard Worker if the output buffer is gradually filled up instead of emptied and re-used from its start, 191*27162e4eSAndroid Build Coastguard Worker one must check if there is enough remaining capacity before each invocation, using LZ4F_compressBound(). 192*27162e4eSAndroid Build Coastguard Worker @return is always the same for a srcSize and prefsPtr. 193*27162e4eSAndroid Build Coastguard Worker prefsPtr is optional : when NULL is provided, preferences will be set to cover worst case scenario. 194*27162e4eSAndroid Build Coastguard Worker tech details : 195*27162e4eSAndroid Build Coastguard Worker @return if automatic flushing is not enabled, includes the possibility that internal buffer might already be filled by up to (blockSize-1) bytes. 196*27162e4eSAndroid Build Coastguard Worker It also includes frame footer (ending + checksum), since it might be generated by LZ4F_compressEnd(). 197*27162e4eSAndroid Build Coastguard Worker @return doesn't include frame header, as it was already generated by LZ4F_compressBegin(). 198*27162e4eSAndroid Build Coastguard Worker 199*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 200*27162e4eSAndroid Build Coastguard Worker 201*27162e4eSAndroid Build Coastguard Worker<pre><b>size_t LZ4F_compressUpdate(LZ4F_cctx* cctx, 202*27162e4eSAndroid Build Coastguard Worker void* dstBuffer, size_t dstCapacity, 203*27162e4eSAndroid Build Coastguard Worker const void* srcBuffer, size_t srcSize, 204*27162e4eSAndroid Build Coastguard Worker const LZ4F_compressOptions_t* cOptPtr); 205*27162e4eSAndroid Build Coastguard Worker</b><p> LZ4F_compressUpdate() can be called repetitively to compress as much data as necessary. 206*27162e4eSAndroid Build Coastguard Worker Important rule: dstCapacity MUST be large enough to ensure operation success even in worst case situations. 207*27162e4eSAndroid Build Coastguard Worker This value is provided by LZ4F_compressBound(). 208*27162e4eSAndroid Build Coastguard Worker If this condition is not respected, LZ4F_compress() will fail (result is an errorCode). 209*27162e4eSAndroid Build Coastguard Worker After an error, the state is left in a UB state, and must be re-initialized or freed. 210*27162e4eSAndroid Build Coastguard Worker If previously an uncompressed block was written, buffered data is flushed 211*27162e4eSAndroid Build Coastguard Worker before appending compressed data is continued. 212*27162e4eSAndroid Build Coastguard Worker `cOptPtr` is optional : NULL can be provided, in which case all options are set to default. 213*27162e4eSAndroid Build Coastguard Worker @return : number of bytes written into `dstBuffer` (it can be zero, meaning input data was just buffered). 214*27162e4eSAndroid Build Coastguard Worker or an error code if it fails (which can be tested using LZ4F_isError()) 215*27162e4eSAndroid Build Coastguard Worker 216*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 217*27162e4eSAndroid Build Coastguard Worker 218*27162e4eSAndroid Build Coastguard Worker<pre><b>size_t LZ4F_flush(LZ4F_cctx* cctx, 219*27162e4eSAndroid Build Coastguard Worker void* dstBuffer, size_t dstCapacity, 220*27162e4eSAndroid Build Coastguard Worker const LZ4F_compressOptions_t* cOptPtr); 221*27162e4eSAndroid Build Coastguard Worker</b><p> When data must be generated and sent immediately, without waiting for a block to be completely filled, 222*27162e4eSAndroid Build Coastguard Worker it's possible to call LZ4_flush(). It will immediately compress any data buffered within cctx. 223*27162e4eSAndroid Build Coastguard Worker `dstCapacity` must be large enough to ensure the operation will be successful. 224*27162e4eSAndroid Build Coastguard Worker `cOptPtr` is optional : it's possible to provide NULL, all options will be set to default. 225*27162e4eSAndroid Build Coastguard Worker @return : nb of bytes written into dstBuffer (can be zero, when there is no data stored within cctx) 226*27162e4eSAndroid Build Coastguard Worker or an error code if it fails (which can be tested using LZ4F_isError()) 227*27162e4eSAndroid Build Coastguard Worker Note : LZ4F_flush() is guaranteed to be successful when dstCapacity >= LZ4F_compressBound(0, prefsPtr). 228*27162e4eSAndroid Build Coastguard Worker 229*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 230*27162e4eSAndroid Build Coastguard Worker 231*27162e4eSAndroid Build Coastguard Worker<pre><b>size_t LZ4F_compressEnd(LZ4F_cctx* cctx, 232*27162e4eSAndroid Build Coastguard Worker void* dstBuffer, size_t dstCapacity, 233*27162e4eSAndroid Build Coastguard Worker const LZ4F_compressOptions_t* cOptPtr); 234*27162e4eSAndroid Build Coastguard Worker</b><p> To properly finish an LZ4 frame, invoke LZ4F_compressEnd(). 235*27162e4eSAndroid Build Coastguard Worker It will flush whatever data remained within `cctx` (like LZ4_flush()) 236*27162e4eSAndroid Build Coastguard Worker and properly finalize the frame, with an endMark and a checksum. 237*27162e4eSAndroid Build Coastguard Worker `cOptPtr` is optional : NULL can be provided, in which case all options will be set to default. 238*27162e4eSAndroid Build Coastguard Worker @return : nb of bytes written into dstBuffer, necessarily >= 4 (endMark), 239*27162e4eSAndroid Build Coastguard Worker or an error code if it fails (which can be tested using LZ4F_isError()) 240*27162e4eSAndroid Build Coastguard Worker Note : LZ4F_compressEnd() is guaranteed to be successful when dstCapacity >= LZ4F_compressBound(0, prefsPtr). 241*27162e4eSAndroid Build Coastguard Worker A successful call to LZ4F_compressEnd() makes `cctx` available again for another compression task. 242*27162e4eSAndroid Build Coastguard Worker 243*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 244*27162e4eSAndroid Build Coastguard Worker 245*27162e4eSAndroid Build Coastguard Worker<a name="Chapter9"></a><h2>Decompression functions</h2><pre></pre> 246*27162e4eSAndroid Build Coastguard Worker 247*27162e4eSAndroid Build Coastguard Worker<pre><b>typedef struct { 248*27162e4eSAndroid Build Coastguard Worker unsigned stableDst; /* pledges that last 64KB decompressed data is present right before @dstBuffer pointer. 249*27162e4eSAndroid Build Coastguard Worker * This optimization skips internal storage operations. 250*27162e4eSAndroid Build Coastguard Worker * Once set, this pledge must remain valid up to the end of current frame. */ 251*27162e4eSAndroid Build Coastguard Worker unsigned skipChecksums; /* disable checksum calculation and verification, even when one is present in frame, to save CPU time. 252*27162e4eSAndroid Build Coastguard Worker * Setting this option to 1 once disables all checksums for the rest of the frame. */ 253*27162e4eSAndroid Build Coastguard Worker unsigned reserved1; </b>/* must be set to zero for forward compatibility */<b> 254*27162e4eSAndroid Build Coastguard Worker unsigned reserved0; </b>/* idem */<b> 255*27162e4eSAndroid Build Coastguard Worker} LZ4F_decompressOptions_t; 256*27162e4eSAndroid Build Coastguard Worker</b></pre><BR> 257*27162e4eSAndroid Build Coastguard Worker<pre><b>LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_dctx** dctxPtr, unsigned version); 258*27162e4eSAndroid Build Coastguard WorkerLZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx); 259*27162e4eSAndroid Build Coastguard Worker</b><p> Create an LZ4F_dctx object, to track all decompression operations. 260*27162e4eSAndroid Build Coastguard Worker @version provided MUST be LZ4F_VERSION. 261*27162e4eSAndroid Build Coastguard Worker @dctxPtr MUST be valid. 262*27162e4eSAndroid Build Coastguard Worker The function fills @dctxPtr with the value of a pointer to an allocated and initialized LZ4F_dctx object. 263*27162e4eSAndroid Build Coastguard Worker The @return is an errorCode, which can be tested using LZ4F_isError(). 264*27162e4eSAndroid Build Coastguard Worker dctx memory can be released using LZ4F_freeDecompressionContext(); 265*27162e4eSAndroid Build Coastguard Worker Result of LZ4F_freeDecompressionContext() indicates current state of decompressionContext when being released. 266*27162e4eSAndroid Build Coastguard Worker That is, it should be == 0 if decompression has been completed fully and correctly. 267*27162e4eSAndroid Build Coastguard Worker 268*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 269*27162e4eSAndroid Build Coastguard Worker 270*27162e4eSAndroid Build Coastguard Worker<a name="Chapter10"></a><h2>Streaming decompression functions</h2><pre></pre> 271*27162e4eSAndroid Build Coastguard Worker 272*27162e4eSAndroid Build Coastguard Worker<pre><b>size_t LZ4F_headerSize(const void* src, size_t srcSize); 273*27162e4eSAndroid Build Coastguard Worker</b><p> Provide the header size of a frame starting at `src`. 274*27162e4eSAndroid Build Coastguard Worker `srcSize` must be >= LZ4F_MIN_SIZE_TO_KNOW_HEADER_LENGTH, 275*27162e4eSAndroid Build Coastguard Worker which is enough to decode the header length. 276*27162e4eSAndroid Build Coastguard Worker @return : size of frame header 277*27162e4eSAndroid Build Coastguard Worker or an error code, which can be tested using LZ4F_isError() 278*27162e4eSAndroid Build Coastguard Worker note : Frame header size is variable, but is guaranteed to be 279*27162e4eSAndroid Build Coastguard Worker >= LZ4F_HEADER_SIZE_MIN bytes, and <= LZ4F_HEADER_SIZE_MAX bytes. 280*27162e4eSAndroid Build Coastguard Worker 281*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 282*27162e4eSAndroid Build Coastguard Worker 283*27162e4eSAndroid Build Coastguard Worker<pre><b>size_t 284*27162e4eSAndroid Build Coastguard WorkerLZ4F_getFrameInfo(LZ4F_dctx* dctx, 285*27162e4eSAndroid Build Coastguard Worker LZ4F_frameInfo_t* frameInfoPtr, 286*27162e4eSAndroid Build Coastguard Worker const void* srcBuffer, size_t* srcSizePtr); 287*27162e4eSAndroid Build Coastguard Worker</b><p> This function extracts frame parameters (max blockSize, dictID, etc.). 288*27162e4eSAndroid Build Coastguard Worker Its usage is optional: user can also invoke LZ4F_decompress() directly. 289*27162e4eSAndroid Build Coastguard Worker 290*27162e4eSAndroid Build Coastguard Worker Extracted information will fill an existing LZ4F_frameInfo_t structure. 291*27162e4eSAndroid Build Coastguard Worker This can be useful for allocation and dictionary identification purposes. 292*27162e4eSAndroid Build Coastguard Worker 293*27162e4eSAndroid Build Coastguard Worker LZ4F_getFrameInfo() can work in the following situations : 294*27162e4eSAndroid Build Coastguard Worker 295*27162e4eSAndroid Build Coastguard Worker 1) At the beginning of a new frame, before any invocation of LZ4F_decompress(). 296*27162e4eSAndroid Build Coastguard Worker It will decode header from `srcBuffer`, 297*27162e4eSAndroid Build Coastguard Worker consuming the header and starting the decoding process. 298*27162e4eSAndroid Build Coastguard Worker 299*27162e4eSAndroid Build Coastguard Worker Input size must be large enough to contain the full frame header. 300*27162e4eSAndroid Build Coastguard Worker Frame header size can be known beforehand by LZ4F_headerSize(). 301*27162e4eSAndroid Build Coastguard Worker Frame header size is variable, but is guaranteed to be >= LZ4F_HEADER_SIZE_MIN bytes, 302*27162e4eSAndroid Build Coastguard Worker and not more than <= LZ4F_HEADER_SIZE_MAX bytes. 303*27162e4eSAndroid Build Coastguard Worker Hence, blindly providing LZ4F_HEADER_SIZE_MAX bytes or more will always work. 304*27162e4eSAndroid Build Coastguard Worker It's allowed to provide more input data than the header size, 305*27162e4eSAndroid Build Coastguard Worker LZ4F_getFrameInfo() will only consume the header. 306*27162e4eSAndroid Build Coastguard Worker 307*27162e4eSAndroid Build Coastguard Worker If input size is not large enough, 308*27162e4eSAndroid Build Coastguard Worker aka if it's smaller than header size, 309*27162e4eSAndroid Build Coastguard Worker function will fail and return an error code. 310*27162e4eSAndroid Build Coastguard Worker 311*27162e4eSAndroid Build Coastguard Worker 2) After decoding has been started, 312*27162e4eSAndroid Build Coastguard Worker it's possible to invoke LZ4F_getFrameInfo() anytime 313*27162e4eSAndroid Build Coastguard Worker to extract already decoded frame parameters stored within dctx. 314*27162e4eSAndroid Build Coastguard Worker 315*27162e4eSAndroid Build Coastguard Worker Note that, if decoding has barely started, 316*27162e4eSAndroid Build Coastguard Worker and not yet read enough information to decode the header, 317*27162e4eSAndroid Build Coastguard Worker LZ4F_getFrameInfo() will fail. 318*27162e4eSAndroid Build Coastguard Worker 319*27162e4eSAndroid Build Coastguard Worker The number of bytes consumed from srcBuffer will be updated in *srcSizePtr (necessarily <= original value). 320*27162e4eSAndroid Build Coastguard Worker LZ4F_getFrameInfo() only consumes bytes when decoding has not yet started, 321*27162e4eSAndroid Build Coastguard Worker and when decoding the header has been successful. 322*27162e4eSAndroid Build Coastguard Worker Decompression must then resume from (srcBuffer + *srcSizePtr). 323*27162e4eSAndroid Build Coastguard Worker 324*27162e4eSAndroid Build Coastguard Worker @return : a hint about how many srcSize bytes LZ4F_decompress() expects for next call, 325*27162e4eSAndroid Build Coastguard Worker or an error code which can be tested using LZ4F_isError(). 326*27162e4eSAndroid Build Coastguard Worker note 1 : in case of error, dctx is not modified. Decoding operation can resume from beginning safely. 327*27162e4eSAndroid Build Coastguard Worker note 2 : frame parameters are *copied into* an already allocated LZ4F_frameInfo_t structure. 328*27162e4eSAndroid Build Coastguard Worker 329*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 330*27162e4eSAndroid Build Coastguard Worker 331*27162e4eSAndroid Build Coastguard Worker<pre><b>size_t 332*27162e4eSAndroid Build Coastguard WorkerLZ4F_decompress(LZ4F_dctx* dctx, 333*27162e4eSAndroid Build Coastguard Worker void* dstBuffer, size_t* dstSizePtr, 334*27162e4eSAndroid Build Coastguard Worker const void* srcBuffer, size_t* srcSizePtr, 335*27162e4eSAndroid Build Coastguard Worker const LZ4F_decompressOptions_t* dOptPtr); 336*27162e4eSAndroid Build Coastguard Worker</b><p> Call this function repetitively to regenerate data compressed in `srcBuffer`. 337*27162e4eSAndroid Build Coastguard Worker 338*27162e4eSAndroid Build Coastguard Worker The function requires a valid dctx state. 339*27162e4eSAndroid Build Coastguard Worker It will read up to *srcSizePtr bytes from srcBuffer, 340*27162e4eSAndroid Build Coastguard Worker and decompress data into dstBuffer, of capacity *dstSizePtr. 341*27162e4eSAndroid Build Coastguard Worker 342*27162e4eSAndroid Build Coastguard Worker The nb of bytes consumed from srcBuffer will be written into *srcSizePtr (necessarily <= original value). 343*27162e4eSAndroid Build Coastguard Worker The nb of bytes decompressed into dstBuffer will be written into *dstSizePtr (necessarily <= original value). 344*27162e4eSAndroid Build Coastguard Worker 345*27162e4eSAndroid Build Coastguard Worker The function does not necessarily read all input bytes, so always check value in *srcSizePtr. 346*27162e4eSAndroid Build Coastguard Worker Unconsumed source data must be presented again in subsequent invocations. 347*27162e4eSAndroid Build Coastguard Worker 348*27162e4eSAndroid Build Coastguard Worker `dstBuffer` can freely change between each consecutive function invocation. 349*27162e4eSAndroid Build Coastguard Worker `dstBuffer` content will be overwritten. 350*27162e4eSAndroid Build Coastguard Worker 351*27162e4eSAndroid Build Coastguard Worker Note: if `LZ4F_getFrameInfo()` is called before `LZ4F_decompress()`, srcBuffer must be updated to reflect 352*27162e4eSAndroid Build Coastguard Worker the number of bytes consumed after reading the frame header. Failure to update srcBuffer before calling 353*27162e4eSAndroid Build Coastguard Worker `LZ4F_decompress()` will cause decompression failure or, even worse, successful but incorrect decompression. 354*27162e4eSAndroid Build Coastguard Worker See the `LZ4F_getFrameInfo()` docs for details. 355*27162e4eSAndroid Build Coastguard Worker 356*27162e4eSAndroid Build Coastguard Worker @return : an hint of how many `srcSize` bytes LZ4F_decompress() expects for next call. 357*27162e4eSAndroid Build Coastguard Worker Schematically, it's the size of the current (or remaining) compressed block + header of next block. 358*27162e4eSAndroid Build Coastguard Worker Respecting the hint provides some small speed benefit, because it skips intermediate buffers. 359*27162e4eSAndroid Build Coastguard Worker This is just a hint though, it's always possible to provide any srcSize. 360*27162e4eSAndroid Build Coastguard Worker 361*27162e4eSAndroid Build Coastguard Worker When a frame is fully decoded, @return will be 0 (no more data expected). 362*27162e4eSAndroid Build Coastguard Worker When provided with more bytes than necessary to decode a frame, 363*27162e4eSAndroid Build Coastguard Worker LZ4F_decompress() will stop reading exactly at end of current frame, and @return 0. 364*27162e4eSAndroid Build Coastguard Worker 365*27162e4eSAndroid Build Coastguard Worker If decompression failed, @return is an error code, which can be tested using LZ4F_isError(). 366*27162e4eSAndroid Build Coastguard Worker After a decompression error, the `dctx` context is not resumable. 367*27162e4eSAndroid Build Coastguard Worker Use LZ4F_resetDecompressionContext() to return to clean state. 368*27162e4eSAndroid Build Coastguard Worker 369*27162e4eSAndroid Build Coastguard Worker After a frame is fully decoded, dctx can be used again to decompress another frame. 370*27162e4eSAndroid Build Coastguard Worker 371*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 372*27162e4eSAndroid Build Coastguard Worker 373*27162e4eSAndroid Build Coastguard Worker<pre><b>void LZ4F_resetDecompressionContext(LZ4F_dctx* dctx); </b>/* always successful */<b> 374*27162e4eSAndroid Build Coastguard Worker</b><p> In case of an error, the context is left in "undefined" state. 375*27162e4eSAndroid Build Coastguard Worker In which case, it's necessary to reset it, before re-using it. 376*27162e4eSAndroid Build Coastguard Worker This method can also be used to abruptly stop any unfinished decompression, 377*27162e4eSAndroid Build Coastguard Worker and start a new one using same context resources. 378*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 379*27162e4eSAndroid Build Coastguard Worker 380*27162e4eSAndroid Build Coastguard Worker<a name="Chapter11"></a><h2>Dictionary compression API</h2><pre></pre> 381*27162e4eSAndroid Build Coastguard Worker 382*27162e4eSAndroid Build Coastguard Worker<pre><b>size_t 383*27162e4eSAndroid Build Coastguard WorkerLZ4F_compressBegin_usingDict(LZ4F_cctx* cctx, 384*27162e4eSAndroid Build Coastguard Worker void* dstBuffer, size_t dstCapacity, 385*27162e4eSAndroid Build Coastguard Worker const void* dictBuffer, size_t dictSize, 386*27162e4eSAndroid Build Coastguard Worker const LZ4F_preferences_t* prefsPtr); 387*27162e4eSAndroid Build Coastguard Worker</b><p> Inits dictionary compression streaming, and writes the frame header into dstBuffer. 388*27162e4eSAndroid Build Coastguard Worker @dstCapacity must be >= LZ4F_HEADER_SIZE_MAX bytes. 389*27162e4eSAndroid Build Coastguard Worker @prefsPtr is optional : one may provide NULL as argument, 390*27162e4eSAndroid Build Coastguard Worker however, it's the only way to provide dictID in the frame header. 391*27162e4eSAndroid Build Coastguard Worker @dictBuffer must outlive the compression session. 392*27162e4eSAndroid Build Coastguard Worker @return : number of bytes written into dstBuffer for the header, 393*27162e4eSAndroid Build Coastguard Worker or an error code (which can be tested using LZ4F_isError()) 394*27162e4eSAndroid Build Coastguard Worker NOTE: The LZ4Frame spec allows each independent block to be compressed with the dictionary, 395*27162e4eSAndroid Build Coastguard Worker but this entry supports a more limited scenario, where only the first block uses the dictionary. 396*27162e4eSAndroid Build Coastguard Worker This is still useful for small data, which only need one block anyway. 397*27162e4eSAndroid Build Coastguard Worker For larger inputs, one may be more interested in LZ4F_compressFrame_usingCDict() below. 398*27162e4eSAndroid Build Coastguard Worker 399*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 400*27162e4eSAndroid Build Coastguard Worker 401*27162e4eSAndroid Build Coastguard Worker<pre><b>size_t 402*27162e4eSAndroid Build Coastguard WorkerLZ4F_decompress_usingDict(LZ4F_dctx* dctxPtr, 403*27162e4eSAndroid Build Coastguard Worker void* dstBuffer, size_t* dstSizePtr, 404*27162e4eSAndroid Build Coastguard Worker const void* srcBuffer, size_t* srcSizePtr, 405*27162e4eSAndroid Build Coastguard Worker const void* dict, size_t dictSize, 406*27162e4eSAndroid Build Coastguard Worker const LZ4F_decompressOptions_t* decompressOptionsPtr); 407*27162e4eSAndroid Build Coastguard Worker</b><p> Same as LZ4F_decompress(), using a predefined dictionary. 408*27162e4eSAndroid Build Coastguard Worker Dictionary is used "in place", without any preprocessing. 409*27162e4eSAndroid Build Coastguard Worker It must remain accessible throughout the entire frame decoding. 410*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 411*27162e4eSAndroid Build Coastguard Worker 412*27162e4eSAndroid Build Coastguard Worker<a name="Chapter12"></a><h2>Bulk processing dictionary compression</h2><pre></pre> 413*27162e4eSAndroid Build Coastguard Worker 414*27162e4eSAndroid Build Coastguard Worker<pre><b>LZ4F_CDict* LZ4F_createCDict(const void* dictBuffer, size_t dictSize); 415*27162e4eSAndroid Build Coastguard Workervoid LZ4F_freeCDict(LZ4F_CDict* CDict); 416*27162e4eSAndroid Build Coastguard Worker</b><p> When compressing multiple messages / blocks using the same dictionary, it's recommended to initialize it just once. 417*27162e4eSAndroid Build Coastguard Worker LZ4_createCDict() will create a digested dictionary, ready to start future compression operations without startup delay. 418*27162e4eSAndroid Build Coastguard Worker LZ4_CDict can be created once and shared by multiple threads concurrently, since its usage is read-only. 419*27162e4eSAndroid Build Coastguard Worker @dictBuffer can be released after LZ4_CDict creation, since its content is copied within CDict. 420*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 421*27162e4eSAndroid Build Coastguard Worker 422*27162e4eSAndroid Build Coastguard Worker<pre><b>size_t 423*27162e4eSAndroid Build Coastguard WorkerLZ4F_compressFrame_usingCDict(LZ4F_cctx* cctx, 424*27162e4eSAndroid Build Coastguard Worker void* dst, size_t dstCapacity, 425*27162e4eSAndroid Build Coastguard Worker const void* src, size_t srcSize, 426*27162e4eSAndroid Build Coastguard Worker const LZ4F_CDict* cdict, 427*27162e4eSAndroid Build Coastguard Worker const LZ4F_preferences_t* preferencesPtr); 428*27162e4eSAndroid Build Coastguard Worker</b><p> Compress an entire srcBuffer into a valid LZ4 frame using a digested Dictionary. 429*27162e4eSAndroid Build Coastguard Worker @cctx must point to a context created by LZ4F_createCompressionContext(). 430*27162e4eSAndroid Build Coastguard Worker If @cdict==NULL, compress without a dictionary. 431*27162e4eSAndroid Build Coastguard Worker @dstBuffer MUST be >= LZ4F_compressFrameBound(srcSize, preferencesPtr). 432*27162e4eSAndroid Build Coastguard Worker If this condition is not respected, function will fail (@return an errorCode). 433*27162e4eSAndroid Build Coastguard Worker The LZ4F_preferences_t structure is optional : one may provide NULL as argument, 434*27162e4eSAndroid Build Coastguard Worker but it's not recommended, as it's the only way to provide @dictID in the frame header. 435*27162e4eSAndroid Build Coastguard Worker @return : number of bytes written into dstBuffer. 436*27162e4eSAndroid Build Coastguard Worker or an error code if it fails (can be tested using LZ4F_isError()) 437*27162e4eSAndroid Build Coastguard Worker Note: for larger inputs generating multiple independent blocks, 438*27162e4eSAndroid Build Coastguard Worker this entry point uses the dictionary for each block. 439*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 440*27162e4eSAndroid Build Coastguard Worker 441*27162e4eSAndroid Build Coastguard Worker<pre><b>size_t 442*27162e4eSAndroid Build Coastguard WorkerLZ4F_compressBegin_usingCDict(LZ4F_cctx* cctx, 443*27162e4eSAndroid Build Coastguard Worker void* dstBuffer, size_t dstCapacity, 444*27162e4eSAndroid Build Coastguard Worker const LZ4F_CDict* cdict, 445*27162e4eSAndroid Build Coastguard Worker const LZ4F_preferences_t* prefsPtr); 446*27162e4eSAndroid Build Coastguard Worker</b><p> Inits streaming dictionary compression, and writes the frame header into dstBuffer. 447*27162e4eSAndroid Build Coastguard Worker @dstCapacity must be >= LZ4F_HEADER_SIZE_MAX bytes. 448*27162e4eSAndroid Build Coastguard Worker @prefsPtr is optional : one may provide NULL as argument, 449*27162e4eSAndroid Build Coastguard Worker note however that it's the only way to insert a @dictID in the frame header. 450*27162e4eSAndroid Build Coastguard Worker @cdict must outlive the compression session. 451*27162e4eSAndroid Build Coastguard Worker @return : number of bytes written into dstBuffer for the header, 452*27162e4eSAndroid Build Coastguard Worker or an error code, which can be tested using LZ4F_isError(). 453*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 454*27162e4eSAndroid Build Coastguard Worker 455*27162e4eSAndroid Build Coastguard Worker<pre><b>typedef enum { LZ4F_LIST_ERRORS(LZ4F_GENERATE_ENUM) 456*27162e4eSAndroid Build Coastguard Worker _LZ4F_dummy_error_enum_for_c89_never_used } LZ4F_errorCodes; 457*27162e4eSAndroid Build Coastguard Worker</b></pre><BR> 458*27162e4eSAndroid Build Coastguard Worker<a name="Chapter13"></a><h2>Advanced compression operations</h2><pre></pre> 459*27162e4eSAndroid Build Coastguard Worker 460*27162e4eSAndroid Build Coastguard Worker<pre><b>LZ4FLIB_STATIC_API size_t LZ4F_getBlockSize(LZ4F_blockSizeID_t blockSizeID); 461*27162e4eSAndroid Build Coastguard Worker</b><p> @return, in scalar format (size_t), 462*27162e4eSAndroid Build Coastguard Worker the maximum block size associated with @blockSizeID, 463*27162e4eSAndroid Build Coastguard Worker or an error code (can be tested using LZ4F_isError()) if @blockSizeID is invalid. 464*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 465*27162e4eSAndroid Build Coastguard Worker 466*27162e4eSAndroid Build Coastguard Worker<pre><b>LZ4FLIB_STATIC_API size_t 467*27162e4eSAndroid Build Coastguard WorkerLZ4F_uncompressedUpdate(LZ4F_cctx* cctx, 468*27162e4eSAndroid Build Coastguard Worker void* dstBuffer, size_t dstCapacity, 469*27162e4eSAndroid Build Coastguard Worker const void* srcBuffer, size_t srcSize, 470*27162e4eSAndroid Build Coastguard Worker const LZ4F_compressOptions_t* cOptPtr); 471*27162e4eSAndroid Build Coastguard Worker</b><p> LZ4F_uncompressedUpdate() can be called repetitively to add data stored as uncompressed blocks. 472*27162e4eSAndroid Build Coastguard Worker Important rule: dstCapacity MUST be large enough to store the entire source buffer as 473*27162e4eSAndroid Build Coastguard Worker no compression is done for this operation 474*27162e4eSAndroid Build Coastguard Worker If this condition is not respected, LZ4F_uncompressedUpdate() will fail (result is an errorCode). 475*27162e4eSAndroid Build Coastguard Worker After an error, the state is left in a UB state, and must be re-initialized or freed. 476*27162e4eSAndroid Build Coastguard Worker If previously a compressed block was written, buffered data is flushed first, 477*27162e4eSAndroid Build Coastguard Worker before appending uncompressed data is continued. 478*27162e4eSAndroid Build Coastguard Worker This operation is only supported when LZ4F_blockIndependent is used. 479*27162e4eSAndroid Build Coastguard Worker `cOptPtr` is optional : NULL can be provided, in which case all options are set to default. 480*27162e4eSAndroid Build Coastguard Worker @return : number of bytes written into `dstBuffer` (it can be zero, meaning input data was just buffered). 481*27162e4eSAndroid Build Coastguard Worker or an error code if it fails (which can be tested using LZ4F_isError()) 482*27162e4eSAndroid Build Coastguard Worker 483*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 484*27162e4eSAndroid Build Coastguard Worker 485*27162e4eSAndroid Build Coastguard Worker<a name="Chapter14"></a><h2>Custom memory allocation</h2><pre></pre> 486*27162e4eSAndroid Build Coastguard Worker 487*27162e4eSAndroid Build Coastguard Worker<pre><b>typedef void* (*LZ4F_AllocFunction) (void* opaqueState, size_t size); 488*27162e4eSAndroid Build Coastguard Workertypedef void* (*LZ4F_CallocFunction) (void* opaqueState, size_t size); 489*27162e4eSAndroid Build Coastguard Workertypedef void (*LZ4F_FreeFunction) (void* opaqueState, void* address); 490*27162e4eSAndroid Build Coastguard Workertypedef struct { 491*27162e4eSAndroid Build Coastguard Worker LZ4F_AllocFunction customAlloc; 492*27162e4eSAndroid Build Coastguard Worker LZ4F_CallocFunction customCalloc; </b>/* optional; when not defined, uses customAlloc + memset */<b> 493*27162e4eSAndroid Build Coastguard Worker LZ4F_FreeFunction customFree; 494*27162e4eSAndroid Build Coastguard Worker void* opaqueState; 495*27162e4eSAndroid Build Coastguard Worker} LZ4F_CustomMem; 496*27162e4eSAndroid Build Coastguard Workerstatic 497*27162e4eSAndroid Build Coastguard Worker#ifdef __GNUC__ 498*27162e4eSAndroid Build Coastguard Worker__attribute__((__unused__)) 499*27162e4eSAndroid Build Coastguard Worker#endif 500*27162e4eSAndroid Build Coastguard WorkerLZ4F_CustomMem const LZ4F_defaultCMem = { NULL, NULL, NULL, NULL }; </b>/**< this constant defers to stdlib's functions */<b> 501*27162e4eSAndroid Build Coastguard Worker</b><p> These prototypes make it possible to pass custom allocation/free functions. 502*27162e4eSAndroid Build Coastguard Worker LZ4F_customMem is provided at state creation time, using LZ4F_create*_advanced() listed below. 503*27162e4eSAndroid Build Coastguard Worker All allocation/free operations will be completed using these custom variants instead of regular <stdlib.h> ones. 504*27162e4eSAndroid Build Coastguard Worker 505*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 506*27162e4eSAndroid Build Coastguard Worker 507*27162e4eSAndroid Build Coastguard Worker</html> 508*27162e4eSAndroid Build Coastguard Worker</body> 509