Seekable compression demo

doc/zstd_manual.html

@@ -28,6 +28,9 @@
 <li><a href="#Chapter18">Buffer-less streaming compression (synchronous mode)</a></li>
 <li><a href="#Chapter19">Buffer-less streaming decompression (synchronous mode)</a></li>
 <li><a href="#Chapter20">Block functions</a></li>
+<li><a href="#Chapter21">Seekable Format</a></li>
+<li><a href="#Chapter22">Seekable compression - HowTo</a></li>
+<li><a href="#Chapter23">Seekable decompression - HowTo</a></li>
 </ol>
 <hr>
 <a name="Chapter1"></a><h2>Introduction</h2><pre>
@@ -660,5 +663,109 @@ size_t ZSTD_compressBlock  (ZSTD_CCtx* cctx, void* dst, size_t dstCapacity, cons
 size_t ZSTD_decompressBlock(ZSTD_DCtx* dctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize);
 size_t ZSTD_insertBlock(ZSTD_DCtx* dctx, const void* blockStart, size_t blockSize);  </b>/**< insert block into `dctx` history. Useful for uncompressed blocks */<b>
 </pre></b><BR>
+<a name="Chapter21"></a><h2>Seekable Format</h2><pre>
+  The seekable format splits the compressed data into a series of "chunks",
+  each compressed individually so that decompression of a section in the
+  middle of an archive only requires zstd to decompress at most a chunk's
+  worth of extra data, instead of the entire archive.
+<BR></pre>
+
+<a name="Chapter22"></a><h2>Seekable compression - HowTo</h2><pre>  A ZSTD_seekable_CStream object is required to tracking streaming operation.
+  Use ZSTD_seekable_createCStream() and ZSTD_seekable_freeCStream() to create/
+  release resources.
+
+  Streaming objects are reusable to avoid allocation and deallocation,
+  to start a new compression operation call ZSTD_seekable_initCStream() on the
+  compressor.
+
+  Data streamed to the seekable compressor will automatically be split into
+  chunks of size `maxChunkSize` (provided in ZSTD_seekable_initCStream()),
+  or if none is provided, will be cut off whenver ZSTD_endChunk() is called
+  or when the default maximum chunk size is reached (approximately 4GB).
+
+  Use ZSTD_seekable_initCStream() to initialize a ZSTD_seekable_CStream object
+  for a new compression operation.
+  `maxChunkSize` indicates the size at which to automatically start a new
+  seekable frame.  `maxChunkSize == 0` implies the default maximum size.
+  @return : a size hint for input to provide for compression, or an error code
+            checkable with ZSTD_isError()
+
+  Use ZSTD_seekable_compressStream() repetitively to consume input stream.
+  The function will automatically update both `pos` fields.
+  Note that it may not consume the entire input, in which case `pos < size`,
+  and it's up to the caller to present again remaining data.
+  @return : a size hint, preferred nb of bytes to use as input for next
+            function call or an error code, which can be tested using
+            ZSTD_isError().
+            Note 1 : it's just a hint, to help latency a little, any other
+                     value will work fine.
+            Note 2 : size hint is guaranteed to be <= ZSTD_CStreamInSize()
+
+  At any time, call ZSTD_seekable_endChunk() to end the current chunk and
+  start a new one.
+
+  ZSTD_endStream() will end the current chunk, and then write the seek table
+  so that decompressors can efficiently find compressed chunks.
+  ZSTD_endStream() may return a number > 0 if it was unable to flush all the
+  necessary data to `output`.  In this case, it should be called again until
+  all remaining data is flushed out and 0 is returned.
+<BR></pre>
+
+<h3>Seekable compressor management</h3><pre></pre><b><pre>ZSTD_seekable_CStream* ZSTD_seekable_createCStream(void);
+size_t ZSTD_seekable_freeCStream(ZSTD_seekable_CStream* zcs);
+</pre></b><BR>
+<h3>Seekable compression functions</h3><pre></pre><b><pre>size_t ZSTD_seekable_initCStream(ZSTD_seekable_CStream* zcs, int compressionLevel, unsigned maxChunkSize);
+size_t ZSTD_seekable_compressStream(ZSTD_seekable_CStream* zcs, ZSTD_outBuffer* output, ZSTD_inBuffer* input);
+size_t ZSTD_seekable_endChunk(ZSTD_seekable_CStream* zcs, ZSTD_outBuffer* output);
+size_t ZSTD_seekable_endStream(ZSTD_seekable_CStream* zcs, ZSTD_outBuffer* output);
+</pre></b><BR>
+<a name="Chapter23"></a><h2>Seekable decompression - HowTo</h2><pre>  A ZSTD_seekable_DStream object is required to tracking streaming operation.
+  Use ZSTD_seekable_createDStream() and ZSTD_seekable_freeDStream() to create/
+  release resources.
+
+  Streaming objects are reusable to avoid allocation and deallocation,
+  to start a new compression operation call ZSTD_seekable_initDStream() on the
+  compressor.
+
+  Use ZSTD_seekable_loadSeekTable() to load the seek table from a file.
+  `src` should point to a block of data read from the end of the file,
+  i.e. `src + srcSize` should always be the end of the file.
+  @return : 0 if the table was loaded successfully, or if `srcSize` was too
+            small, a size hint for how much data to provide.
+            An error code may also be returned, checkable with ZSTD_isError()
+
+  Use ZSTD_initDStream to prepare for a new decompression operation using the
+  seektable loaded with ZSTD_seekable_loadSeekTable().
+  Data in the range [rangeStart, rangeEnd) will be decompressed.
+
+  Call ZSTD_seekable_decompressStream() repetitively to consume input stream.
+  @return : There are a number of possible return codes for this function
+           - 0, the decompression operation has completed.
+           - An error code checkable with ZSTD_isError
+             + If this error code is ZSTD_error_needSeek, the user should seek
+               to the file position provided by ZSTD_seekable_getSeekOffset()
+               and indicate this to the stream with
+               ZSTD_seekable_updateOffset(), before resuming decompression
+             + Otherwise, this is a regular decompression error and the input
+               file is likely corrupted or the API was incorrectly used.
+           - A size hint, the preferred nb of bytes to provide as input to the
+             next function call to improve latency.
+
+  ZSTD_seekable_getSeekOffset() and ZSTD_seekable_updateOffset() are helper
+  functions to indicate where the user should seek their file stream to, when
+  a different position is required to continue decompression.
+  Note that ZSTD_seekable_updateOffset will error if given an offset other
+  than the one requested from ZSTD_seekable_getSeekOffset().
+<BR></pre>
+
+<h3>Seekable decompressor management</h3><pre></pre><b><pre>ZSTD_seekable_DStream* ZSTD_seekable_createDStream(void);
+size_t ZSTD_seekable_freeDStream(ZSTD_seekable_DStream* zds);
+</pre></b><BR>
+<h3>Seekable decompression functions</h3><pre></pre><b><pre>size_t ZSTD_seekable_loadSeekTable(ZSTD_seekable_DStream* zds, const void* src, size_t srcSize);
+size_t ZSTD_seekable_initDStream(ZSTD_seekable_DStream* zds, unsigned long long rangeStart, unsigned long long rangeEnd);
+size_t ZSTD_seekable_decompressStream(ZSTD_seekable_DStream* zds, ZSTD_outBuffer* output, ZSTD_inBuffer* input);
+unsigned long long ZSTD_seekable_getSeekOffset(ZSTD_seekable_DStream* zds);
+size_t ZSTD_seekable_updateOffset(ZSTD_seekable_DStream* zds, unsigned long long offset);
+</pre></b><BR>
 </html>
 </body>