127b27ec6Sopenharmony_ci<html> 227b27ec6Sopenharmony_ci<head> 327b27ec6Sopenharmony_ci<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 427b27ec6Sopenharmony_ci<title>1.9.4 Manual</title> 527b27ec6Sopenharmony_ci</head> 627b27ec6Sopenharmony_ci<body> 727b27ec6Sopenharmony_ci<h1>1.9.4 Manual</h1> 827b27ec6Sopenharmony_ci<hr> 927b27ec6Sopenharmony_ci<a name="Contents"></a><h2>Contents</h2> 1027b27ec6Sopenharmony_ci<ol> 1127b27ec6Sopenharmony_ci<li><a href="#Chapter1">Introduction</a></li> 1227b27ec6Sopenharmony_ci<li><a href="#Chapter2">Compiler specifics</a></li> 1327b27ec6Sopenharmony_ci<li><a href="#Chapter3">Error management</a></li> 1427b27ec6Sopenharmony_ci<li><a href="#Chapter4">Frame compression types</a></li> 1527b27ec6Sopenharmony_ci<li><a href="#Chapter5">Simple compression function</a></li> 1627b27ec6Sopenharmony_ci<li><a href="#Chapter6">Advanced compression functions</a></li> 1727b27ec6Sopenharmony_ci<li><a href="#Chapter7">Resource Management</a></li> 1827b27ec6Sopenharmony_ci<li><a href="#Chapter8">Compression</a></li> 1927b27ec6Sopenharmony_ci<li><a href="#Chapter9">Decompression functions</a></li> 2027b27ec6Sopenharmony_ci<li><a href="#Chapter10">Streaming decompression functions</a></li> 2127b27ec6Sopenharmony_ci<li><a href="#Chapter11">Bulk processing dictionary API</a></li> 2227b27ec6Sopenharmony_ci</ol> 2327b27ec6Sopenharmony_ci<hr> 2427b27ec6Sopenharmony_ci<a name="Chapter1"></a><h2>Introduction</h2><pre> 2527b27ec6Sopenharmony_ci lz4frame.h implements LZ4 frame specification: see doc/lz4_Frame_format.md . 2627b27ec6Sopenharmony_ci LZ4 Frames are compatible with `lz4` CLI, 2727b27ec6Sopenharmony_ci and designed to be interoperable with any system. 2827b27ec6Sopenharmony_ci<BR></pre> 2927b27ec6Sopenharmony_ci 3027b27ec6Sopenharmony_ci<a name="Chapter2"></a><h2>Compiler specifics</h2><pre></pre> 3127b27ec6Sopenharmony_ci 3227b27ec6Sopenharmony_ci<a name="Chapter3"></a><h2>Error management</h2><pre></pre> 3327b27ec6Sopenharmony_ci 3427b27ec6Sopenharmony_ci<pre><b>unsigned LZ4F_isError(LZ4F_errorCode_t code); </b>/**< tells when a function result is an error code */<b> 3527b27ec6Sopenharmony_ci</b></pre><BR> 3627b27ec6Sopenharmony_ci<pre><b>const char* LZ4F_getErrorName(LZ4F_errorCode_t code); </b>/**< return error code string; for debugging */<b> 3727b27ec6Sopenharmony_ci</b></pre><BR> 3827b27ec6Sopenharmony_ci<a name="Chapter4"></a><h2>Frame compression types</h2><pre> 3927b27ec6Sopenharmony_ci<BR></pre> 4027b27ec6Sopenharmony_ci 4127b27ec6Sopenharmony_ci<pre><b>typedef enum { 4227b27ec6Sopenharmony_ci LZ4F_default=0, 4327b27ec6Sopenharmony_ci LZ4F_max64KB=4, 4427b27ec6Sopenharmony_ci LZ4F_max256KB=5, 4527b27ec6Sopenharmony_ci LZ4F_max1MB=6, 4627b27ec6Sopenharmony_ci LZ4F_max4MB=7 4727b27ec6Sopenharmony_ci LZ4F_OBSOLETE_ENUM(max64KB) 4827b27ec6Sopenharmony_ci LZ4F_OBSOLETE_ENUM(max256KB) 4927b27ec6Sopenharmony_ci LZ4F_OBSOLETE_ENUM(max1MB) 5027b27ec6Sopenharmony_ci LZ4F_OBSOLETE_ENUM(max4MB) 5127b27ec6Sopenharmony_ci} LZ4F_blockSizeID_t; 5227b27ec6Sopenharmony_ci</b></pre><BR> 5327b27ec6Sopenharmony_ci<pre><b>typedef enum { 5427b27ec6Sopenharmony_ci LZ4F_blockLinked=0, 5527b27ec6Sopenharmony_ci LZ4F_blockIndependent 5627b27ec6Sopenharmony_ci LZ4F_OBSOLETE_ENUM(blockLinked) 5727b27ec6Sopenharmony_ci LZ4F_OBSOLETE_ENUM(blockIndependent) 5827b27ec6Sopenharmony_ci} LZ4F_blockMode_t; 5927b27ec6Sopenharmony_ci</b></pre><BR> 6027b27ec6Sopenharmony_ci<pre><b>typedef enum { 6127b27ec6Sopenharmony_ci LZ4F_noContentChecksum=0, 6227b27ec6Sopenharmony_ci LZ4F_contentChecksumEnabled 6327b27ec6Sopenharmony_ci LZ4F_OBSOLETE_ENUM(noContentChecksum) 6427b27ec6Sopenharmony_ci LZ4F_OBSOLETE_ENUM(contentChecksumEnabled) 6527b27ec6Sopenharmony_ci} LZ4F_contentChecksum_t; 6627b27ec6Sopenharmony_ci</b></pre><BR> 6727b27ec6Sopenharmony_ci<pre><b>typedef enum { 6827b27ec6Sopenharmony_ci LZ4F_noBlockChecksum=0, 6927b27ec6Sopenharmony_ci LZ4F_blockChecksumEnabled 7027b27ec6Sopenharmony_ci} LZ4F_blockChecksum_t; 7127b27ec6Sopenharmony_ci</b></pre><BR> 7227b27ec6Sopenharmony_ci<pre><b>typedef enum { 7327b27ec6Sopenharmony_ci LZ4F_frame=0, 7427b27ec6Sopenharmony_ci LZ4F_skippableFrame 7527b27ec6Sopenharmony_ci LZ4F_OBSOLETE_ENUM(skippableFrame) 7627b27ec6Sopenharmony_ci} LZ4F_frameType_t; 7727b27ec6Sopenharmony_ci</b></pre><BR> 7827b27ec6Sopenharmony_ci<pre><b>typedef struct { 7927b27ec6Sopenharmony_ci LZ4F_blockSizeID_t blockSizeID; </b>/* max64KB, max256KB, max1MB, max4MB; 0 == default */<b> 8027b27ec6Sopenharmony_ci LZ4F_blockMode_t blockMode; </b>/* LZ4F_blockLinked, LZ4F_blockIndependent; 0 == default */<b> 8127b27ec6Sopenharmony_ci LZ4F_contentChecksum_t contentChecksumFlag; </b>/* 1: frame terminated with 32-bit checksum of decompressed data; 0: disabled (default) */<b> 8227b27ec6Sopenharmony_ci LZ4F_frameType_t frameType; </b>/* read-only field : LZ4F_frame or LZ4F_skippableFrame */<b> 8327b27ec6Sopenharmony_ci unsigned long long contentSize; </b>/* Size of uncompressed content ; 0 == unknown */<b> 8427b27ec6Sopenharmony_ci unsigned dictID; </b>/* Dictionary ID, sent by compressor to help decoder select correct dictionary; 0 == no dictID provided */<b> 8527b27ec6Sopenharmony_ci LZ4F_blockChecksum_t blockChecksumFlag; </b>/* 1: each block followed by a checksum of block's compressed data; 0: disabled (default) */<b> 8627b27ec6Sopenharmony_ci} LZ4F_frameInfo_t; 8727b27ec6Sopenharmony_ci</b><p> makes it possible to set or read frame parameters. 8827b27ec6Sopenharmony_ci Structure must be first init to 0, using memset() or LZ4F_INIT_FRAMEINFO, 8927b27ec6Sopenharmony_ci setting all parameters to default. 9027b27ec6Sopenharmony_ci It's then possible to update selectively some parameters 9127b27ec6Sopenharmony_ci</p></pre><BR> 9227b27ec6Sopenharmony_ci 9327b27ec6Sopenharmony_ci<pre><b>typedef struct { 9427b27ec6Sopenharmony_ci LZ4F_frameInfo_t frameInfo; 9527b27ec6Sopenharmony_ci int compressionLevel; </b>/* 0: default (fast mode); values > LZ4HC_CLEVEL_MAX count as LZ4HC_CLEVEL_MAX; values < 0 trigger "fast acceleration" */<b> 9627b27ec6Sopenharmony_ci unsigned autoFlush; </b>/* 1: always flush; reduces usage of internal buffers */<b> 9727b27ec6Sopenharmony_ci 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> 9827b27ec6Sopenharmony_ci unsigned reserved[3]; </b>/* must be zero for forward compatibility */<b> 9927b27ec6Sopenharmony_ci} LZ4F_preferences_t; 10027b27ec6Sopenharmony_ci</b><p> makes it possible to supply advanced compression instructions to streaming interface. 10127b27ec6Sopenharmony_ci Structure must be first init to 0, using memset() or LZ4F_INIT_PREFERENCES, 10227b27ec6Sopenharmony_ci setting all parameters to default. 10327b27ec6Sopenharmony_ci All reserved fields must be set to zero. 10427b27ec6Sopenharmony_ci</p></pre><BR> 10527b27ec6Sopenharmony_ci 10627b27ec6Sopenharmony_ci<a name="Chapter5"></a><h2>Simple compression function</h2><pre></pre> 10727b27ec6Sopenharmony_ci 10827b27ec6Sopenharmony_ci<pre><b>size_t LZ4F_compressFrameBound(size_t srcSize, const LZ4F_preferences_t* preferencesPtr); 10927b27ec6Sopenharmony_ci</b><p> Returns the maximum possible compressed size with LZ4F_compressFrame() given srcSize and preferences. 11027b27ec6Sopenharmony_ci `preferencesPtr` is optional. It can be replaced by NULL, in which case, the function will assume default preferences. 11127b27ec6Sopenharmony_ci Note : this result is only usable with LZ4F_compressFrame(). 11227b27ec6Sopenharmony_ci It may also be relevant to LZ4F_compressUpdate() _only if_ no flush() operation is ever performed. 11327b27ec6Sopenharmony_ci 11427b27ec6Sopenharmony_ci</p></pre><BR> 11527b27ec6Sopenharmony_ci 11627b27ec6Sopenharmony_ci<pre><b>size_t LZ4F_compressFrame(void* dstBuffer, size_t dstCapacity, 11727b27ec6Sopenharmony_ci const void* srcBuffer, size_t srcSize, 11827b27ec6Sopenharmony_ci const LZ4F_preferences_t* preferencesPtr); 11927b27ec6Sopenharmony_ci</b><p> Compress an entire srcBuffer into a valid LZ4 frame. 12027b27ec6Sopenharmony_ci dstCapacity MUST be >= LZ4F_compressFrameBound(srcSize, preferencesPtr). 12127b27ec6Sopenharmony_ci The LZ4F_preferences_t structure is optional : you can provide NULL as argument. All preferences will be set to default. 12227b27ec6Sopenharmony_ci @return : number of bytes written into dstBuffer. 12327b27ec6Sopenharmony_ci or an error code if it fails (can be tested using LZ4F_isError()) 12427b27ec6Sopenharmony_ci 12527b27ec6Sopenharmony_ci</p></pre><BR> 12627b27ec6Sopenharmony_ci 12727b27ec6Sopenharmony_ci<a name="Chapter6"></a><h2>Advanced compression functions</h2><pre></pre> 12827b27ec6Sopenharmony_ci 12927b27ec6Sopenharmony_ci<pre><b>typedef struct { 13027b27ec6Sopenharmony_ci unsigned stableSrc; </b>/* 1 == src content will remain present on future calls to LZ4F_compress(); skip copying src content within tmp buffer */<b> 13127b27ec6Sopenharmony_ci unsigned reserved[3]; 13227b27ec6Sopenharmony_ci} LZ4F_compressOptions_t; 13327b27ec6Sopenharmony_ci</b></pre><BR> 13427b27ec6Sopenharmony_ci<a name="Chapter7"></a><h2>Resource Management</h2><pre></pre> 13527b27ec6Sopenharmony_ci 13627b27ec6Sopenharmony_ci<pre><b>LZ4F_errorCode_t LZ4F_createCompressionContext(LZ4F_cctx** cctxPtr, unsigned version); 13727b27ec6Sopenharmony_ciLZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx); 13827b27ec6Sopenharmony_ci</b><p> The first thing to do is to create a compressionContext object, 13927b27ec6Sopenharmony_ci which will keep track of operation state during streaming compression. 14027b27ec6Sopenharmony_ci This is achieved using LZ4F_createCompressionContext(), which takes as argument a version, 14127b27ec6Sopenharmony_ci and a pointer to LZ4F_cctx*, to write the resulting pointer into. 14227b27ec6Sopenharmony_ci @version provided MUST be LZ4F_VERSION. It is intended to track potential version mismatch, notably when using DLL. 14327b27ec6Sopenharmony_ci The function provides a pointer to a fully allocated LZ4F_cctx object. 14427b27ec6Sopenharmony_ci @cctxPtr MUST be != NULL. 14527b27ec6Sopenharmony_ci If @return != zero, context creation failed. 14627b27ec6Sopenharmony_ci A created compression context can be employed multiple times for consecutive streaming operations. 14727b27ec6Sopenharmony_ci Once all streaming compression jobs are completed, 14827b27ec6Sopenharmony_ci the state object can be released using LZ4F_freeCompressionContext(). 14927b27ec6Sopenharmony_ci Note1 : LZ4F_freeCompressionContext() is always successful. Its return value can be ignored. 15027b27ec6Sopenharmony_ci Note2 : LZ4F_freeCompressionContext() works fine with NULL input pointers (do nothing). 15127b27ec6Sopenharmony_ci</p></pre><BR> 15227b27ec6Sopenharmony_ci 15327b27ec6Sopenharmony_ci<a name="Chapter8"></a><h2>Compression</h2><pre></pre> 15427b27ec6Sopenharmony_ci 15527b27ec6Sopenharmony_ci<pre><b>size_t LZ4F_compressBegin(LZ4F_cctx* cctx, 15627b27ec6Sopenharmony_ci void* dstBuffer, size_t dstCapacity, 15727b27ec6Sopenharmony_ci const LZ4F_preferences_t* prefsPtr); 15827b27ec6Sopenharmony_ci</b><p> will write the frame header into dstBuffer. 15927b27ec6Sopenharmony_ci dstCapacity must be >= LZ4F_HEADER_SIZE_MAX bytes. 16027b27ec6Sopenharmony_ci `prefsPtr` is optional : you can provide NULL as argument, all preferences will then be set to default. 16127b27ec6Sopenharmony_ci @return : number of bytes written into dstBuffer for the header 16227b27ec6Sopenharmony_ci or an error code (which can be tested using LZ4F_isError()) 16327b27ec6Sopenharmony_ci 16427b27ec6Sopenharmony_ci</p></pre><BR> 16527b27ec6Sopenharmony_ci 16627b27ec6Sopenharmony_ci<pre><b>size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr); 16727b27ec6Sopenharmony_ci</b><p> Provides minimum dstCapacity required to guarantee success of 16827b27ec6Sopenharmony_ci LZ4F_compressUpdate(), given a srcSize and preferences, for a worst case scenario. 16927b27ec6Sopenharmony_ci When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() instead. 17027b27ec6Sopenharmony_ci Note that the result is only valid for a single invocation of LZ4F_compressUpdate(). 17127b27ec6Sopenharmony_ci When invoking LZ4F_compressUpdate() multiple times, 17227b27ec6Sopenharmony_ci if the output buffer is gradually filled up instead of emptied and re-used from its start, 17327b27ec6Sopenharmony_ci one must check if there is enough remaining capacity before each invocation, using LZ4F_compressBound(). 17427b27ec6Sopenharmony_ci @return is always the same for a srcSize and prefsPtr. 17527b27ec6Sopenharmony_ci prefsPtr is optional : when NULL is provided, preferences will be set to cover worst case scenario. 17627b27ec6Sopenharmony_ci tech details : 17727b27ec6Sopenharmony_ci @return if automatic flushing is not enabled, includes the possibility that internal buffer might already be filled by up to (blockSize-1) bytes. 17827b27ec6Sopenharmony_ci It also includes frame footer (ending + checksum), since it might be generated by LZ4F_compressEnd(). 17927b27ec6Sopenharmony_ci @return doesn't include frame header, as it was already generated by LZ4F_compressBegin(). 18027b27ec6Sopenharmony_ci 18127b27ec6Sopenharmony_ci</p></pre><BR> 18227b27ec6Sopenharmony_ci 18327b27ec6Sopenharmony_ci<pre><b>size_t LZ4F_compressUpdate(LZ4F_cctx* cctx, 18427b27ec6Sopenharmony_ci void* dstBuffer, size_t dstCapacity, 18527b27ec6Sopenharmony_ci const void* srcBuffer, size_t srcSize, 18627b27ec6Sopenharmony_ci const LZ4F_compressOptions_t* cOptPtr); 18727b27ec6Sopenharmony_ci</b><p> LZ4F_compressUpdate() can be called repetitively to compress as much data as necessary. 18827b27ec6Sopenharmony_ci Important rule: dstCapacity MUST be large enough to ensure operation success even in worst case situations. 18927b27ec6Sopenharmony_ci This value is provided by LZ4F_compressBound(). 19027b27ec6Sopenharmony_ci If this condition is not respected, LZ4F_compress() will fail (result is an errorCode). 19127b27ec6Sopenharmony_ci After an error, the state is left in a UB state, and must be re-initialized or freed. 19227b27ec6Sopenharmony_ci If previously an uncompressed block was written, buffered data is flushed 19327b27ec6Sopenharmony_ci before appending compressed data is continued. 19427b27ec6Sopenharmony_ci `cOptPtr` is optional : NULL can be provided, in which case all options are set to default. 19527b27ec6Sopenharmony_ci @return : number of bytes written into `dstBuffer` (it can be zero, meaning input data was just buffered). 19627b27ec6Sopenharmony_ci or an error code if it fails (which can be tested using LZ4F_isError()) 19727b27ec6Sopenharmony_ci 19827b27ec6Sopenharmony_ci</p></pre><BR> 19927b27ec6Sopenharmony_ci 20027b27ec6Sopenharmony_ci<pre><b>size_t LZ4F_flush(LZ4F_cctx* cctx, 20127b27ec6Sopenharmony_ci void* dstBuffer, size_t dstCapacity, 20227b27ec6Sopenharmony_ci const LZ4F_compressOptions_t* cOptPtr); 20327b27ec6Sopenharmony_ci</b><p> When data must be generated and sent immediately, without waiting for a block to be completely filled, 20427b27ec6Sopenharmony_ci it's possible to call LZ4_flush(). It will immediately compress any data buffered within cctx. 20527b27ec6Sopenharmony_ci `dstCapacity` must be large enough to ensure the operation will be successful. 20627b27ec6Sopenharmony_ci `cOptPtr` is optional : it's possible to provide NULL, all options will be set to default. 20727b27ec6Sopenharmony_ci @return : nb of bytes written into dstBuffer (can be zero, when there is no data stored within cctx) 20827b27ec6Sopenharmony_ci or an error code if it fails (which can be tested using LZ4F_isError()) 20927b27ec6Sopenharmony_ci Note : LZ4F_flush() is guaranteed to be successful when dstCapacity >= LZ4F_compressBound(0, prefsPtr). 21027b27ec6Sopenharmony_ci 21127b27ec6Sopenharmony_ci</p></pre><BR> 21227b27ec6Sopenharmony_ci 21327b27ec6Sopenharmony_ci<pre><b>size_t LZ4F_compressEnd(LZ4F_cctx* cctx, 21427b27ec6Sopenharmony_ci void* dstBuffer, size_t dstCapacity, 21527b27ec6Sopenharmony_ci const LZ4F_compressOptions_t* cOptPtr); 21627b27ec6Sopenharmony_ci</b><p> To properly finish an LZ4 frame, invoke LZ4F_compressEnd(). 21727b27ec6Sopenharmony_ci It will flush whatever data remained within `cctx` (like LZ4_flush()) 21827b27ec6Sopenharmony_ci and properly finalize the frame, with an endMark and a checksum. 21927b27ec6Sopenharmony_ci `cOptPtr` is optional : NULL can be provided, in which case all options will be set to default. 22027b27ec6Sopenharmony_ci @return : nb of bytes written into dstBuffer, necessarily >= 4 (endMark), 22127b27ec6Sopenharmony_ci or an error code if it fails (which can be tested using LZ4F_isError()) 22227b27ec6Sopenharmony_ci Note : LZ4F_compressEnd() is guaranteed to be successful when dstCapacity >= LZ4F_compressBound(0, prefsPtr). 22327b27ec6Sopenharmony_ci A successful call to LZ4F_compressEnd() makes `cctx` available again for another compression task. 22427b27ec6Sopenharmony_ci 22527b27ec6Sopenharmony_ci</p></pre><BR> 22627b27ec6Sopenharmony_ci 22727b27ec6Sopenharmony_ci<a name="Chapter9"></a><h2>Decompression functions</h2><pre></pre> 22827b27ec6Sopenharmony_ci 22927b27ec6Sopenharmony_ci<pre><b>typedef struct { 23027b27ec6Sopenharmony_ci unsigned stableDst; /* pledges that last 64KB decompressed data will remain available unmodified between invocations. 23127b27ec6Sopenharmony_ci * This optimization skips storage operations in tmp buffers. */ 23227b27ec6Sopenharmony_ci unsigned skipChecksums; /* disable checksum calculation and verification, even when one is present in frame, to save CPU time. 23327b27ec6Sopenharmony_ci * Setting this option to 1 once disables all checksums for the rest of the frame. */ 23427b27ec6Sopenharmony_ci unsigned reserved1; </b>/* must be set to zero for forward compatibility */<b> 23527b27ec6Sopenharmony_ci unsigned reserved0; </b>/* idem */<b> 23627b27ec6Sopenharmony_ci} LZ4F_decompressOptions_t; 23727b27ec6Sopenharmony_ci</b></pre><BR> 23827b27ec6Sopenharmony_ci<pre><b>LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_dctx** dctxPtr, unsigned version); 23927b27ec6Sopenharmony_ciLZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx); 24027b27ec6Sopenharmony_ci</b><p> Create an LZ4F_dctx object, to track all decompression operations. 24127b27ec6Sopenharmony_ci @version provided MUST be LZ4F_VERSION. 24227b27ec6Sopenharmony_ci @dctxPtr MUST be valid. 24327b27ec6Sopenharmony_ci The function fills @dctxPtr with the value of a pointer to an allocated and initialized LZ4F_dctx object. 24427b27ec6Sopenharmony_ci The @return is an errorCode, which can be tested using LZ4F_isError(). 24527b27ec6Sopenharmony_ci dctx memory can be released using LZ4F_freeDecompressionContext(); 24627b27ec6Sopenharmony_ci Result of LZ4F_freeDecompressionContext() indicates current state of decompressionContext when being released. 24727b27ec6Sopenharmony_ci That is, it should be == 0 if decompression has been completed fully and correctly. 24827b27ec6Sopenharmony_ci 24927b27ec6Sopenharmony_ci</p></pre><BR> 25027b27ec6Sopenharmony_ci 25127b27ec6Sopenharmony_ci<a name="Chapter10"></a><h2>Streaming decompression functions</h2><pre></pre> 25227b27ec6Sopenharmony_ci 25327b27ec6Sopenharmony_ci<pre><b>size_t LZ4F_headerSize(const void* src, size_t srcSize); 25427b27ec6Sopenharmony_ci</b><p> Provide the header size of a frame starting at `src`. 25527b27ec6Sopenharmony_ci `srcSize` must be >= LZ4F_MIN_SIZE_TO_KNOW_HEADER_LENGTH, 25627b27ec6Sopenharmony_ci which is enough to decode the header length. 25727b27ec6Sopenharmony_ci @return : size of frame header 25827b27ec6Sopenharmony_ci or an error code, which can be tested using LZ4F_isError() 25927b27ec6Sopenharmony_ci note : Frame header size is variable, but is guaranteed to be 26027b27ec6Sopenharmony_ci >= LZ4F_HEADER_SIZE_MIN bytes, and <= LZ4F_HEADER_SIZE_MAX bytes. 26127b27ec6Sopenharmony_ci 26227b27ec6Sopenharmony_ci</p></pre><BR> 26327b27ec6Sopenharmony_ci 26427b27ec6Sopenharmony_ci<pre><b>size_t 26527b27ec6Sopenharmony_ciLZ4F_getFrameInfo(LZ4F_dctx* dctx, 26627b27ec6Sopenharmony_ci LZ4F_frameInfo_t* frameInfoPtr, 26727b27ec6Sopenharmony_ci const void* srcBuffer, size_t* srcSizePtr); 26827b27ec6Sopenharmony_ci</b><p> This function extracts frame parameters (max blockSize, dictID, etc.). 26927b27ec6Sopenharmony_ci Its usage is optional: user can also invoke LZ4F_decompress() directly. 27027b27ec6Sopenharmony_ci 27127b27ec6Sopenharmony_ci Extracted information will fill an existing LZ4F_frameInfo_t structure. 27227b27ec6Sopenharmony_ci This can be useful for allocation and dictionary identification purposes. 27327b27ec6Sopenharmony_ci 27427b27ec6Sopenharmony_ci LZ4F_getFrameInfo() can work in the following situations : 27527b27ec6Sopenharmony_ci 27627b27ec6Sopenharmony_ci 1) At the beginning of a new frame, before any invocation of LZ4F_decompress(). 27727b27ec6Sopenharmony_ci It will decode header from `srcBuffer`, 27827b27ec6Sopenharmony_ci consuming the header and starting the decoding process. 27927b27ec6Sopenharmony_ci 28027b27ec6Sopenharmony_ci Input size must be large enough to contain the full frame header. 28127b27ec6Sopenharmony_ci Frame header size can be known beforehand by LZ4F_headerSize(). 28227b27ec6Sopenharmony_ci Frame header size is variable, but is guaranteed to be >= LZ4F_HEADER_SIZE_MIN bytes, 28327b27ec6Sopenharmony_ci and not more than <= LZ4F_HEADER_SIZE_MAX bytes. 28427b27ec6Sopenharmony_ci Hence, blindly providing LZ4F_HEADER_SIZE_MAX bytes or more will always work. 28527b27ec6Sopenharmony_ci It's allowed to provide more input data than the header size, 28627b27ec6Sopenharmony_ci LZ4F_getFrameInfo() will only consume the header. 28727b27ec6Sopenharmony_ci 28827b27ec6Sopenharmony_ci If input size is not large enough, 28927b27ec6Sopenharmony_ci aka if it's smaller than header size, 29027b27ec6Sopenharmony_ci function will fail and return an error code. 29127b27ec6Sopenharmony_ci 29227b27ec6Sopenharmony_ci 2) After decoding has been started, 29327b27ec6Sopenharmony_ci it's possible to invoke LZ4F_getFrameInfo() anytime 29427b27ec6Sopenharmony_ci to extract already decoded frame parameters stored within dctx. 29527b27ec6Sopenharmony_ci 29627b27ec6Sopenharmony_ci Note that, if decoding has barely started, 29727b27ec6Sopenharmony_ci and not yet read enough information to decode the header, 29827b27ec6Sopenharmony_ci LZ4F_getFrameInfo() will fail. 29927b27ec6Sopenharmony_ci 30027b27ec6Sopenharmony_ci The number of bytes consumed from srcBuffer will be updated in *srcSizePtr (necessarily <= original value). 30127b27ec6Sopenharmony_ci LZ4F_getFrameInfo() only consumes bytes when decoding has not yet started, 30227b27ec6Sopenharmony_ci and when decoding the header has been successful. 30327b27ec6Sopenharmony_ci Decompression must then resume from (srcBuffer + *srcSizePtr). 30427b27ec6Sopenharmony_ci 30527b27ec6Sopenharmony_ci @return : a hint about how many srcSize bytes LZ4F_decompress() expects for next call, 30627b27ec6Sopenharmony_ci or an error code which can be tested using LZ4F_isError(). 30727b27ec6Sopenharmony_ci note 1 : in case of error, dctx is not modified. Decoding operation can resume from beginning safely. 30827b27ec6Sopenharmony_ci note 2 : frame parameters are *copied into* an already allocated LZ4F_frameInfo_t structure. 30927b27ec6Sopenharmony_ci 31027b27ec6Sopenharmony_ci</p></pre><BR> 31127b27ec6Sopenharmony_ci 31227b27ec6Sopenharmony_ci<pre><b>size_t 31327b27ec6Sopenharmony_ciLZ4F_decompress(LZ4F_dctx* dctx, 31427b27ec6Sopenharmony_ci void* dstBuffer, size_t* dstSizePtr, 31527b27ec6Sopenharmony_ci const void* srcBuffer, size_t* srcSizePtr, 31627b27ec6Sopenharmony_ci const LZ4F_decompressOptions_t* dOptPtr); 31727b27ec6Sopenharmony_ci</b><p> Call this function repetitively to regenerate data compressed in `srcBuffer`. 31827b27ec6Sopenharmony_ci 31927b27ec6Sopenharmony_ci The function requires a valid dctx state. 32027b27ec6Sopenharmony_ci It will read up to *srcSizePtr bytes from srcBuffer, 32127b27ec6Sopenharmony_ci and decompress data into dstBuffer, of capacity *dstSizePtr. 32227b27ec6Sopenharmony_ci 32327b27ec6Sopenharmony_ci The nb of bytes consumed from srcBuffer will be written into *srcSizePtr (necessarily <= original value). 32427b27ec6Sopenharmony_ci The nb of bytes decompressed into dstBuffer will be written into *dstSizePtr (necessarily <= original value). 32527b27ec6Sopenharmony_ci 32627b27ec6Sopenharmony_ci The function does not necessarily read all input bytes, so always check value in *srcSizePtr. 32727b27ec6Sopenharmony_ci Unconsumed source data must be presented again in subsequent invocations. 32827b27ec6Sopenharmony_ci 32927b27ec6Sopenharmony_ci `dstBuffer` can freely change between each consecutive function invocation. 33027b27ec6Sopenharmony_ci `dstBuffer` content will be overwritten. 33127b27ec6Sopenharmony_ci 33227b27ec6Sopenharmony_ci @return : an hint of how many `srcSize` bytes LZ4F_decompress() expects for next call. 33327b27ec6Sopenharmony_ci Schematically, it's the size of the current (or remaining) compressed block + header of next block. 33427b27ec6Sopenharmony_ci Respecting the hint provides some small speed benefit, because it skips intermediate buffers. 33527b27ec6Sopenharmony_ci This is just a hint though, it's always possible to provide any srcSize. 33627b27ec6Sopenharmony_ci 33727b27ec6Sopenharmony_ci When a frame is fully decoded, @return will be 0 (no more data expected). 33827b27ec6Sopenharmony_ci When provided with more bytes than necessary to decode a frame, 33927b27ec6Sopenharmony_ci LZ4F_decompress() will stop reading exactly at end of current frame, and @return 0. 34027b27ec6Sopenharmony_ci 34127b27ec6Sopenharmony_ci If decompression failed, @return is an error code, which can be tested using LZ4F_isError(). 34227b27ec6Sopenharmony_ci After a decompression error, the `dctx` context is not resumable. 34327b27ec6Sopenharmony_ci Use LZ4F_resetDecompressionContext() to return to clean state. 34427b27ec6Sopenharmony_ci 34527b27ec6Sopenharmony_ci After a frame is fully decoded, dctx can be used again to decompress another frame. 34627b27ec6Sopenharmony_ci 34727b27ec6Sopenharmony_ci</p></pre><BR> 34827b27ec6Sopenharmony_ci 34927b27ec6Sopenharmony_ci<pre><b>void LZ4F_resetDecompressionContext(LZ4F_dctx* dctx); </b>/* always successful */<b> 35027b27ec6Sopenharmony_ci</b><p> In case of an error, the context is left in "undefined" state. 35127b27ec6Sopenharmony_ci In which case, it's necessary to reset it, before re-using it. 35227b27ec6Sopenharmony_ci This method can also be used to abruptly stop any unfinished decompression, 35327b27ec6Sopenharmony_ci and start a new one using same context resources. 35427b27ec6Sopenharmony_ci</p></pre><BR> 35527b27ec6Sopenharmony_ci 35627b27ec6Sopenharmony_ci<pre><b>typedef enum { LZ4F_LIST_ERRORS(LZ4F_GENERATE_ENUM) 35727b27ec6Sopenharmony_ci _LZ4F_dummy_error_enum_for_c89_never_used } LZ4F_errorCodes; 35827b27ec6Sopenharmony_ci</b></pre><BR> 35927b27ec6Sopenharmony_ci<pre><b>LZ4FLIB_STATIC_API size_t LZ4F_getBlockSize(LZ4F_blockSizeID_t blockSizeID); 36027b27ec6Sopenharmony_ci</b><p> Return, in scalar format (size_t), 36127b27ec6Sopenharmony_ci the maximum block size associated with blockSizeID. 36227b27ec6Sopenharmony_ci</p></pre><BR> 36327b27ec6Sopenharmony_ci 36427b27ec6Sopenharmony_ci<pre><b>LZ4FLIB_STATIC_API size_t 36527b27ec6Sopenharmony_ciLZ4F_uncompressedUpdate(LZ4F_cctx* cctx, 36627b27ec6Sopenharmony_ci void* dstBuffer, size_t dstCapacity, 36727b27ec6Sopenharmony_ci const void* srcBuffer, size_t srcSize, 36827b27ec6Sopenharmony_ci const LZ4F_compressOptions_t* cOptPtr); 36927b27ec6Sopenharmony_ci</b><p> LZ4F_uncompressedUpdate() can be called repetitively to add as much data uncompressed data as necessary. 37027b27ec6Sopenharmony_ci Important rule: dstCapacity MUST be large enough to store the entire source buffer as 37127b27ec6Sopenharmony_ci no compression is done for this operation 37227b27ec6Sopenharmony_ci If this condition is not respected, LZ4F_uncompressedUpdate() will fail (result is an errorCode). 37327b27ec6Sopenharmony_ci After an error, the state is left in a UB state, and must be re-initialized or freed. 37427b27ec6Sopenharmony_ci If previously a compressed block was written, buffered data is flushed 37527b27ec6Sopenharmony_ci before appending uncompressed data is continued. 37627b27ec6Sopenharmony_ci This is only supported when LZ4F_blockIndependent is used 37727b27ec6Sopenharmony_ci `cOptPtr` is optional : NULL can be provided, in which case all options are set to default. 37827b27ec6Sopenharmony_ci @return : number of bytes written into `dstBuffer` (it can be zero, meaning input data was just buffered). 37927b27ec6Sopenharmony_ci or an error code if it fails (which can be tested using LZ4F_isError()) 38027b27ec6Sopenharmony_ci 38127b27ec6Sopenharmony_ci</p></pre><BR> 38227b27ec6Sopenharmony_ci 38327b27ec6Sopenharmony_ci<a name="Chapter11"></a><h2>Bulk processing dictionary API</h2><pre></pre> 38427b27ec6Sopenharmony_ci 38527b27ec6Sopenharmony_ci<pre><b>LZ4FLIB_STATIC_API LZ4F_CDict* LZ4F_createCDict(const void* dictBuffer, size_t dictSize); 38627b27ec6Sopenharmony_ciLZ4FLIB_STATIC_API void LZ4F_freeCDict(LZ4F_CDict* CDict); 38727b27ec6Sopenharmony_ci</b><p> When compressing multiple messages / blocks using the same dictionary, it's recommended to load it just once. 38827b27ec6Sopenharmony_ci LZ4_createCDict() will create a digested dictionary, ready to start future compression operations without startup delay. 38927b27ec6Sopenharmony_ci LZ4_CDict can be created once and shared by multiple threads concurrently, since its usage is read-only. 39027b27ec6Sopenharmony_ci `dictBuffer` can be released after LZ4_CDict creation, since its content is copied within CDict 39127b27ec6Sopenharmony_ci</p></pre><BR> 39227b27ec6Sopenharmony_ci 39327b27ec6Sopenharmony_ci<pre><b>LZ4FLIB_STATIC_API size_t 39427b27ec6Sopenharmony_ciLZ4F_compressFrame_usingCDict(LZ4F_cctx* cctx, 39527b27ec6Sopenharmony_ci void* dst, size_t dstCapacity, 39627b27ec6Sopenharmony_ci const void* src, size_t srcSize, 39727b27ec6Sopenharmony_ci const LZ4F_CDict* cdict, 39827b27ec6Sopenharmony_ci const LZ4F_preferences_t* preferencesPtr); 39927b27ec6Sopenharmony_ci</b><p> Compress an entire srcBuffer into a valid LZ4 frame using a digested Dictionary. 40027b27ec6Sopenharmony_ci cctx must point to a context created by LZ4F_createCompressionContext(). 40127b27ec6Sopenharmony_ci If cdict==NULL, compress without a dictionary. 40227b27ec6Sopenharmony_ci dstBuffer MUST be >= LZ4F_compressFrameBound(srcSize, preferencesPtr). 40327b27ec6Sopenharmony_ci If this condition is not respected, function will fail (@return an errorCode). 40427b27ec6Sopenharmony_ci The LZ4F_preferences_t structure is optional : you may provide NULL as argument, 40527b27ec6Sopenharmony_ci but it's not recommended, as it's the only way to provide dictID in the frame header. 40627b27ec6Sopenharmony_ci @return : number of bytes written into dstBuffer. 40727b27ec6Sopenharmony_ci or an error code if it fails (can be tested using LZ4F_isError()) 40827b27ec6Sopenharmony_ci</p></pre><BR> 40927b27ec6Sopenharmony_ci 41027b27ec6Sopenharmony_ci<pre><b>LZ4FLIB_STATIC_API size_t 41127b27ec6Sopenharmony_ciLZ4F_compressBegin_usingCDict(LZ4F_cctx* cctx, 41227b27ec6Sopenharmony_ci void* dstBuffer, size_t dstCapacity, 41327b27ec6Sopenharmony_ci const LZ4F_CDict* cdict, 41427b27ec6Sopenharmony_ci const LZ4F_preferences_t* prefsPtr); 41527b27ec6Sopenharmony_ci</b><p> Inits streaming dictionary compression, and writes the frame header into dstBuffer. 41627b27ec6Sopenharmony_ci dstCapacity must be >= LZ4F_HEADER_SIZE_MAX bytes. 41727b27ec6Sopenharmony_ci `prefsPtr` is optional : you may provide NULL as argument, 41827b27ec6Sopenharmony_ci however, it's the only way to provide dictID in the frame header. 41927b27ec6Sopenharmony_ci @return : number of bytes written into dstBuffer for the header, 42027b27ec6Sopenharmony_ci or an error code (which can be tested using LZ4F_isError()) 42127b27ec6Sopenharmony_ci</p></pre><BR> 42227b27ec6Sopenharmony_ci 42327b27ec6Sopenharmony_ci<pre><b>LZ4FLIB_STATIC_API size_t 42427b27ec6Sopenharmony_ciLZ4F_decompress_usingDict(LZ4F_dctx* dctxPtr, 42527b27ec6Sopenharmony_ci void* dstBuffer, size_t* dstSizePtr, 42627b27ec6Sopenharmony_ci const void* srcBuffer, size_t* srcSizePtr, 42727b27ec6Sopenharmony_ci const void* dict, size_t dictSize, 42827b27ec6Sopenharmony_ci const LZ4F_decompressOptions_t* decompressOptionsPtr); 42927b27ec6Sopenharmony_ci</b><p> Same as LZ4F_decompress(), using a predefined dictionary. 43027b27ec6Sopenharmony_ci Dictionary is used "in place", without any preprocessing. 43127b27ec6Sopenharmony_ci It must remain accessible throughout the entire frame decoding. 43227b27ec6Sopenharmony_ci</p></pre><BR> 43327b27ec6Sopenharmony_ci 43427b27ec6Sopenharmony_ci<pre><b>typedef void* (*LZ4F_AllocFunction) (void* opaqueState, size_t size); 43527b27ec6Sopenharmony_citypedef void* (*LZ4F_CallocFunction) (void* opaqueState, size_t size); 43627b27ec6Sopenharmony_citypedef void (*LZ4F_FreeFunction) (void* opaqueState, void* address); 43727b27ec6Sopenharmony_citypedef struct { 43827b27ec6Sopenharmony_ci LZ4F_AllocFunction customAlloc; 43927b27ec6Sopenharmony_ci LZ4F_CallocFunction customCalloc; </b>/* optional; when not defined, uses customAlloc + memset */<b> 44027b27ec6Sopenharmony_ci LZ4F_FreeFunction customFree; 44127b27ec6Sopenharmony_ci void* opaqueState; 44227b27ec6Sopenharmony_ci} LZ4F_CustomMem; 44327b27ec6Sopenharmony_cistatic 44427b27ec6Sopenharmony_ci#ifdef __GNUC__ 44527b27ec6Sopenharmony_ci__attribute__((__unused__)) 44627b27ec6Sopenharmony_ci#endif 44727b27ec6Sopenharmony_ciLZ4F_CustomMem const LZ4F_defaultCMem = { NULL, NULL, NULL, NULL }; </b>/**< this constant defers to stdlib's functions */<b> 44827b27ec6Sopenharmony_ci</b><p> These prototypes make it possible to pass custom allocation/free functions. 44927b27ec6Sopenharmony_ci LZ4F_customMem is provided at state creation time, using LZ4F_create*_advanced() listed below. 45027b27ec6Sopenharmony_ci All allocation/free operations will be completed using these custom variants instead of regular <stdlib.h> ones. 45127b27ec6Sopenharmony_ci 45227b27ec6Sopenharmony_ci</p></pre><BR> 45327b27ec6Sopenharmony_ci 45427b27ec6Sopenharmony_ci</html> 45527b27ec6Sopenharmony_ci</body> 456