/*

 * Copyright (c) 2016-present, Yann Collet, Facebook, Inc.

 * All rights reserved.

 *

 * This source code is licensed under both the BSD-style license (found in the

 * LICENSE file in the root directory of this source tree) and the GPLv2 (found

 * in the COPYING file in the root directory of this source tree).

 * You may select, at your option, one of the above-listed licenses.

 */

#if defined (__cplusplus)

extern "C" {

#endif

#ifndef ZSTD_H_235446

#define ZSTD_H_235446

/* ======   Dependency   ======*/

#include <stddef.h>   /* size_t */

/* =====   ZSTDLIB_API : control library symbols visibility   ===== */

#ifndef ZSTDLIB_VISIBILITY

#  if defined(__GNUC__) && (__GNUC__ >= 4)

#    define ZSTDLIB_VISIBILITY __attribute__ ((visibility ("default")))

#  else

#    define ZSTDLIB_VISIBILITY

#  endif

#endif

#if defined(ZSTD_DLL_EXPORT) && (ZSTD_DLL_EXPORT==1)

#  define ZSTDLIB_API __declspec(dllexport) ZSTDLIB_VISIBILITY

#elif defined(ZSTD_DLL_IMPORT) && (ZSTD_DLL_IMPORT==1)

#  define ZSTDLIB_API __declspec(dllimport) ZSTDLIB_VISIBILITY /* It isn't required but allows to generate better code, saving a function pointer load from the IAT and an indirect jump.*/

#else

#  define ZSTDLIB_API ZSTDLIB_VISIBILITY

#endif

/*******************************************************************************

  Introduction

  zstd, short for Zstandard, is a fast lossless compression algorithm, targeting

  real-time compression scenarios at zlib-level and better compression ratios.

  The zstd compression library provides in-memory compression and decompression

  functions.

  The library supports regular compression levels from 1 up to ZSTD_maxCLevel(),

  which is currently 22. Levels >= 20, labeled `--ultra`, should be used with

  caution, as they require more memory. The library also offers negative

  compression levels, which extend the range of speed vs. ratio preferences.

  The lower the level, the faster the speed (at the cost of compression).

  Compression can be done in:

    - a single step (described as Simple API)

    - a single step, reusing a context (described as Explicit context)

    - unbounded multiple steps (described as Streaming compression)

  The compression ratio achievable on small data can be highly improved using

  a dictionary. Dictionary compression can be performed in:

    - a single step (described as Simple dictionary API)

    - a single step, reusing a dictionary (described as Bulk-processing

      dictionary API)

  Advanced experimental functions can be accessed using

  `#define ZSTD_STATIC_LINKING_ONLY` before including zstd.h.

  Advanced experimental APIs should never be used with a dynamically-linked

  library. They are not "stable"; their definitions or signatures may change in

  the future. Only static linking is allowed.

*******************************************************************************/

/*------   Version   ------*/

#define ZSTD_VERSION_MAJOR    1

#define ZSTD_VERSION_MINOR    3

#define ZSTD_VERSION_NUMBER  (ZSTD_VERSION_MAJOR *100*100 + ZSTD_VERSION_MINOR *100 + ZSTD_VERSION_RELEASE)

#define ZSTD_LIB_VERSION ZSTD_VERSION_MAJOR.ZSTD_VERSION_MINOR.ZSTD_VERSION_RELEASE

#define ZSTD_QUOTE(str) #str

#define ZSTD_EXPAND_AND_QUOTE(str) ZSTD_QUOTE(str)

#define ZSTD_VERSION_STRING ZSTD_EXPAND_AND_QUOTE(ZSTD_LIB_VERSION)

/***************************************

*  Default constant

***************************************/

#ifndef ZSTD_CLEVEL_DEFAULT

#  define ZSTD_CLEVEL_DEFAULT 3

#endif

/***************************************

*  Simple API

***************************************/

/*! ZSTD_compress() :

 *  Compresses `src` content as a single zstd compressed frame into already allocated `dst`.

 *  Hint : compression runs faster if `dstCapacity` >=  `ZSTD_compressBound(srcSize)`.

 *  @return : compressed size written into `dst` (<= `dstCapacity),

 *            or an error code if it fails (which can be tested using ZSTD_isError()). */

ZSTDLIB_API size_t ZSTD_compress( void* dst, size_t dstCapacity,

                            const void* src, size_t srcSize,

                                  int compressionLevel);

/*! ZSTD_decompress() :

 *  `compressedSize` : must be the _exact_ size of some number of compressed and/or skippable frames.

 *  `dstCapacity` is an upper bound of originalSize to regenerate.

 *  If user cannot imply a maximum upper bound, it's better to use streaming mode to decompress data.

 *  @return : the number of bytes decompressed into `dst` (<= `dstCapacity`),

 *            or an errorCode if it fails (which can be tested using ZSTD_isError()). */

ZSTDLIB_API size_t ZSTD_decompress( void* dst, size_t dstCapacity,

                              const void* src, size_t compressedSize);

 *  `src` should point to the start of a ZSTD encoded frame.

 *  `srcSize` must be at least as large as the frame header.

 *            hint : any size >= `ZSTD_frameHeaderSize_max` is large enough.

 *  @return : - decompressed size of `src` frame content, if known

 *            - ZSTD_CONTENTSIZE_UNKNOWN if the size cannot be determined

 *            - ZSTD_CONTENTSIZE_ERROR if an error occurred (e.g. invalid magic number, srcSize too small)

 *   note 1 : a 0 return value means the frame is valid but "empty".

 *   note 2 : decompressed size is an optional field, it may not be present, typically in streaming mode.

 *            When `return==ZSTD_CONTENTSIZE_UNKNOWN`, data to decompress could be any size.

 *            In which case, it's necessary to use streaming mode to decompress data.

 *            Optionally, application can rely on some implicit limit,

 *            as ZSTD_decompress() only needs an upper bound of decompressed size.

 *            (For example, data could be necessarily cut into blocks <= 16 KB).

 *   note 3 : decompressed size is always present when compression is completed using single-pass functions,

 *            such as ZSTD_compress(), ZSTD_compressCCtx() ZSTD_compress_usingDict() or ZSTD_compress_usingCDict().

 *   note 4 : decompressed size can be very large (64-bits value),

 *            potentially larger than what local system can handle as a single memory segment.

 *            In which case, it's necessary to use streaming mode to decompress data.

 *   note 5 : If source is untrusted, decompressed size could be wrong or intentionally modified.

 *            Always ensure return value fits within application's authorized limits.

 *            Each application can set its own limits.

 *   note 6 : This function replaces ZSTD_getDecompressedSize() */

#define ZSTD_CONTENTSIZE_UNKNOWN (0ULL - 1)

#define ZSTD_CONTENTSIZE_ERROR   (0ULL - 2)

ZSTDLIB_API unsigned long long ZSTD_getFrameContentSize(const void *src, size_t srcSize);

/*! ZSTD_getDecompressedSize() :

 *  NOTE: This function is now obsolete, in favor of ZSTD_getFrameContentSize().

 *  Both functions work the same way, but ZSTD_getDecompressedSize() blends

 *  "empty", "unknown" and "error" results to the same return value (0),

 *  while ZSTD_getFrameContentSize() gives them separate return values.

 * @return : decompressed size of `src` frame content _if known and not empty_, 0 otherwise. */

ZSTDLIB_API unsigned long long ZSTD_getDecompressedSize(const void* src, size_t srcSize);

/*======  Helper functions  ======*/

#define ZSTD_COMPRESSBOUND(srcSize)   ((srcSize) + ((srcSize)>>8) + (((srcSize) < (128<<10)) ? (((128<<10) - (srcSize)) >> 11) /* margin, from 64 to 0 */ : 0))  /* this formula ensures that bound(A) + bound(B) <= bound(A+B) as long as A and B >= 128 KB */

ZSTDLIB_API size_t      ZSTD_compressBound(size_t srcSize); /*!< maximum compressed size in worst case single-pass scenario */

ZSTDLIB_API unsigned    ZSTD_isError(size_t code);          /*!< tells if a `size_t` function result is an error code */

ZSTDLIB_API const char* ZSTD_getErrorName(size_t code);     /*!< provides readable string from an error code */

ZSTDLIB_API int         ZSTD_maxCLevel(void);               /*!< maximum compression level available */

/***************************************

*  Explicit context

***************************************/

/*= Compression context

 *  When compressing many times,

 *  it is recommended to allocate a context just once, and re-use it for each successive compression operation.

 *  This will make workload friendlier for system's memory.

 *  Use one context per thread for parallel execution in multi-threaded environments. */

typedef struct ZSTD_CCtx_s ZSTD_CCtx;

ZSTDLIB_API ZSTD_CCtx* ZSTD_createCCtx(void);

ZSTDLIB_API size_t     ZSTD_freeCCtx(ZSTD_CCtx* cctx);

/*! ZSTD_compressCCtx() :

                                     void* dst, size_t dstCapacity,

                               const void* src, size_t srcSize,

                                     int compressionLevel);

/*= Decompression context

 *  When decompressing many times,

 *  it is recommended to allocate a context only once,

 *  and re-use it for each successive compression operation.

 *  This will make workload friendlier for system's memory.

 *  Use one context per thread for parallel execution. */

typedef struct ZSTD_DCtx_s ZSTD_DCtx;

ZSTDLIB_API ZSTD_DCtx* ZSTD_createDCtx(void);

ZSTDLIB_API size_t     ZSTD_freeDCtx(ZSTD_DCtx* dctx);

/*! ZSTD_decompressDCtx() :

                                       void* dst, size_t dstCapacity,

                                 const void* src, size_t srcSize);

/**************************

*  Simple dictionary API

***************************/

/*! ZSTD_compress_usingDict() :

 *  Note : This function loads the dictionary, resulting in significant startup delay.

ZSTDLIB_API size_t ZSTD_compress_usingDict(ZSTD_CCtx* ctx,

                                           void* dst, size_t dstCapacity,

                                     const void* src, size_t srcSize,

                                     const void* dict,size_t dictSize,

                                           int compressionLevel);

/*! ZSTD_decompress_usingDict() :

 *  Dictionary must be identical to the one used during compression.

 *  Note : This function loads the dictionary, resulting in significant startup delay.

 *  Note : When `dict == NULL || dictSize < 8` no dictionary is used. */

ZSTDLIB_API size_t ZSTD_decompress_usingDict(ZSTD_DCtx* dctx,

                                             void* dst, size_t dstCapacity,

                                       const void* src, size_t srcSize,

                                       const void* dict,size_t dictSize);

 *  Bulk processing dictionary API

typedef struct ZSTD_CDict_s ZSTD_CDict;

/*! ZSTD_createCDict() :

 *  ZSTD_CDict can be created once and shared by multiple threads concurrently, since its usage is read-only.

ZSTDLIB_API ZSTD_CDict* ZSTD_createCDict(const void* dictBuffer, size_t dictSize,

                                         int compressionLevel);

/*! ZSTD_freeCDict() :

 *  Function frees memory allocated by ZSTD_createCDict(). */

ZSTDLIB_API size_t      ZSTD_freeCDict(ZSTD_CDict* CDict);

/*! ZSTD_compress_usingCDict() :

 *  Compression using a digested Dictionary.

ZSTDLIB_API size_t ZSTD_compress_usingCDict(ZSTD_CCtx* cctx,

                                            void* dst, size_t dstCapacity,

                                      const void* src, size_t srcSize,

                                      const ZSTD_CDict* cdict);

typedef struct ZSTD_DDict_s ZSTD_DDict;

/*! ZSTD_createDDict() :

 *  Create a digested dictionary, ready to start decompression operation without startup delay.

ZSTDLIB_API ZSTD_DDict* ZSTD_createDDict(const void* dictBuffer, size_t dictSize);

/*! ZSTD_freeDDict() :

 *  Function frees memory allocated with ZSTD_createDDict() */

ZSTDLIB_API size_t      ZSTD_freeDDict(ZSTD_DDict* ddict);

/*! ZSTD_decompress_usingDDict() :

 *  Decompression using a digested Dictionary.

ZSTDLIB_API size_t ZSTD_decompress_usingDDict(ZSTD_DCtx* dctx,

                                              void* dst, size_t dstCapacity,

                                        const void* src, size_t srcSize,

                                        const ZSTD_DDict* ddict);

/****************************

*  Streaming

****************************/

typedef struct ZSTD_inBuffer_s {

  const void* src;    /**< start of input buffer */

  size_t size;        /**< size of input buffer */

  size_t pos;         /**< position where reading stopped. Will be updated. Necessarily 0 <= pos <= size */

} ZSTD_inBuffer;

typedef struct ZSTD_outBuffer_s {

  void*  dst;         /**< start of output buffer */

  size_t size;        /**< size of output buffer */

  size_t pos;         /**< position where writing stopped. Will be updated. Necessarily 0 <= pos <= size */

} ZSTD_outBuffer;

/*-***********************************************************************

*  Streaming compression - HowTo

*

*  A ZSTD_CStream object is required to track streaming operation.

*  Use ZSTD_createCStream() and ZSTD_freeCStream() to create/release resources.

*  ZSTD_CStream objects can be reused multiple times on consecutive compression operations.

*

*

*  Use ZSTD_compressStream() as many times as necessary to consume input stream.

*  The function will automatically update both `pos` fields within `input` and `output`.

*  Note that the function may not consume the entire input,

*  for example, because the output buffer is already full,

*  in which case `input.pos < input.size`.

*  The caller must check if input has been entirely consumed.

*  If not, the caller must make some room to receive more compressed data,

*  and then present again remaining input data.

*

*  At any moment, it's possible to flush whatever data might remain stuck within internal buffer,

*  using ZSTD_flushStream(). `output->pos` will be updated.

*  Note that, if `output->size` is too small, a single invocation of ZSTD_flushStream() might not be enough (return code > 0).

*  In which case, make some room to receive more compressed data, and call again ZSTD_flushStream().

*  @return : 0 if internal buffers are entirely flushed,

*            >0 if some data still present within internal buffer (the value is minimal estimation of remaining size),

*            or an error code, which can be tested using ZSTD_isError().

*

*  ZSTD_endStream() instructs to finish a frame.

*  It will perform a flush and write frame epilogue.

*  The epilogue is required for decoders to consider a frame completed.

*  flush() operation is the same, and follows same rules as ZSTD_flushStream().

*  @return : 0 if frame fully completed and fully flushed,

*            >0 if some data still present within internal buffer (the value is minimal estimation of remaining size),

*            or an error code, which can be tested using ZSTD_isError().

*

* *******************************************************************/

typedef ZSTD_CCtx ZSTD_CStream;  /**< CCtx and CStream are now effectively same object (>= v1.3.0) */

                                 /* Continue to distinguish them for compatibility with older versions <= v1.2.0 */

/*===== ZSTD_CStream management functions =====*/

ZSTDLIB_API ZSTD_CStream* ZSTD_createCStream(void);

ZSTDLIB_API size_t ZSTD_freeCStream(ZSTD_CStream* zcs);

/*===== Streaming compression functions =====*/

ZSTDLIB_API size_t ZSTD_initCStream(ZSTD_CStream* zcs, int compressionLevel);

ZSTDLIB_API size_t ZSTD_compressStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output, ZSTD_inBuffer* input);

ZSTDLIB_API size_t ZSTD_flushStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output);

ZSTDLIB_API size_t ZSTD_endStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output);

ZSTDLIB_API size_t ZSTD_CStreamInSize(void);    /**< recommended size for input buffer */

ZSTDLIB_API size_t ZSTD_CStreamOutSize(void);   /**< recommended size for output buffer. Guarantee to successfully flush at least one complete compressed block in all circumstances. */

/*-***************************************************************************

*  Streaming decompression - HowTo

*

*  A ZSTD_DStream object is required to track streaming operations.

*  Use ZSTD_createDStream() and ZSTD_freeDStream() to create/release resources.

*  ZSTD_DStream objects can be re-used multiple times.

*

*

*  Use ZSTD_decompressStream() repetitively to consume your input.

*  The function will update both `pos` fields.

*  If `input.pos < input.size`, some input has not been consumed.

*  It's up to the caller to present again remaining data.

*  If `output.pos < output.size`, decoder has flushed everything it could.

* *******************************************************************************/

typedef ZSTD_DCtx ZSTD_DStream;  /**< DCtx and DStream are now effectively same object (>= v1.3.0) */

/*===== ZSTD_DStream management functions =====*/

ZSTDLIB_API ZSTD_DStream* ZSTD_createDStream(void);

ZSTDLIB_API size_t ZSTD_freeDStream(ZSTD_DStream* zds);

/*===== Streaming decompression functions =====*/

ZSTDLIB_API size_t ZSTD_initDStream(ZSTD_DStream* zds);

ZSTDLIB_API size_t ZSTD_decompressStream(ZSTD_DStream* zds, ZSTD_outBuffer* output, ZSTD_inBuffer* input);

ZSTDLIB_API size_t ZSTD_DStreamInSize(void);    /*!< recommended size for input buffer */

ZSTDLIB_API size_t ZSTD_DStreamOutSize(void);   /*!< recommended size for output buffer. Guarantee to successfully flush at least one complete block in all circumstances. */

#endif  /* ZSTD_H_235446 */

/****************************************************************************************

 *   ADVANCED AND EXPERIMENTAL FUNCTIONS

 ****************************************************************************************

 * They should never be used with a dynamic library, as prototypes may change in the future.

 * Use them only in association with static linking.

 * ***************************************************************************************/

ZSTDLIB_API int ZSTD_minCLevel(void);  /*!< minimum negative compression level allowed */