view release on metacpan or  search on metacpan

ext/zstd/contrib/seekable_format/zstd_seekable.h  view on Meta::CPAN

#ifndef SEEKABLE_H
#define SEEKABLE_H

#if defined (__cplusplus)
extern "C" {
#endif

#include <stdio.h>
#include "zstd.h"   /* ZSTDLIB_API */


#define ZSTD_seekTableFooterSize 9

#define ZSTD_SEEKABLE_MAGICNUMBER 0x8F92EAB1

#define ZSTD_SEEKABLE_MAXFRAMES 0x8000000U

/* Limit maximum size to avoid potential issues storing the compressed size */
#define ZSTD_SEEKABLE_MAX_FRAME_DECOMPRESSED_SIZE 0x40000000U

/*-****************************************************************************
*  Seekable Format
*
*  The seekable format splits the compressed data into a series of "frames",
*  each compressed individually so that decompression of a section in the
*  middle of an archive only requires zstd to decompress at most a frame's
*  worth of extra data, instead of the entire archive.
******************************************************************************/

typedef struct ZSTD_seekable_CStream_s ZSTD_seekable_CStream;
typedef struct ZSTD_seekable_s ZSTD_seekable;
typedef struct ZSTD_seekTable_s ZSTD_seekTable;

/*-****************************************************************************
*  Seekable compression - HowTo
*  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
*  frames of size `maxFrameSize` (provided in ZSTD_seekable_initCStream()),
*  or if none is provided, will be cut off whenever ZSTD_seekable_endFrame() is
*  called or when the default maximum frame size (2GB) is reached.
*
*  Use ZSTD_seekable_initCStream() to initialize a ZSTD_seekable_CStream object
*  for a new compression operation.
*  - `maxFrameSize` indicates the size at which to automatically start a new
*            seekable frame.
*            `maxFrameSize == 0` implies the default maximum size.
*            Smaller frame sizes allow faster decompression of small segments,
*            since retrieving a single byte requires decompression of
*            the full frame where the byte belongs.
*            In general, size the frames to roughly correspond to
*            the access granularity (when it's known).
*            But small sizes also reduce compression ratio.
*            Avoid really tiny frame sizes (< 1 KB),
*            that would hurt compression ratio considerably.
*  - `checksumFlag` indicates whether or not the seek table should include frame
*            checksums on the uncompressed data for verification.
*  @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.
*
*  At any time, call ZSTD_seekable_endFrame() to end the current frame and
*  start a new one.
*
*  ZSTD_seekable_endStream() will end the current frame, and then write the seek
*  table so that decompressors can efficiently find compressed frames.
*  ZSTD_seekable_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.
******************************************************************************/

/*===== Seekable compressor management =====*/
ZSTDLIB_API ZSTD_seekable_CStream* ZSTD_seekable_createCStream(void);
ZSTDLIB_API size_t ZSTD_seekable_freeCStream(ZSTD_seekable_CStream* zcs);

/*===== Seekable compression functions =====*/
ZSTDLIB_API size_t ZSTD_seekable_initCStream(ZSTD_seekable_CStream* zcs, int compressionLevel, int checksumFlag, unsigned maxFrameSize);
ZSTDLIB_API size_t ZSTD_seekable_compressStream(ZSTD_seekable_CStream* zcs, ZSTD_outBuffer* output, ZSTD_inBuffer* input);
ZSTDLIB_API size_t ZSTD_seekable_endFrame(ZSTD_seekable_CStream* zcs, ZSTD_outBuffer* output);
ZSTDLIB_API size_t ZSTD_seekable_endStream(ZSTD_seekable_CStream* zcs, ZSTD_outBuffer* output);