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