[*] Initial commit

lonetix/include/df/cpr/xz.h

@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+
+/**
+ * \file cpr/xz.h
+ *
+ * Compressors, LZMA/LZMA2 encoding and decoding implementation.
+ *
+ * \copyright The DoubleFourteen Code Forge (C) All Rights Reserved
+ * \author    Lorenzo Cogotti
+ */
+
+#ifndef DF_CPR_XZ_H_
+#define DF_CPR_XZ_H_
+
+#include "stm.h"
+
+/// LZMA/LZMA2 stream handle.
+typedef struct XzStmObj *XzStmHn;
+
+/// LZMA/LZMA2 data integrity checksum algorithms.
+typedef enum {
+	XZCHK_NONE   = 0,  ///< Do not include any data checksum
+	XZCHK_CRC32  = 1,  ///< Cyclic Redundancy Check, 32-bit
+	XZCHK_CRC64  = 4,  ///< Cyclic Redundancy Check, 64-bit
+	XZCHK_SHA256 = 10  ///< Secure Hash Algorithm, 256 bit
+} Xzchk;
+
+/// LZMA/LZMA2 compressor flags.
+typedef struct {
+	unsigned compress;  ///< Compression level, range [0-9]
+	Boolean  extreme;   ///< Severely sacrifice speed for compression
+	Xzchk    chk;       ///< Checksum algorithm to use
+	size_t   bufsiz;    ///< Output buffer size in bytes
+} XzEncOpts;
+
+/// LZMA/LZMA2 decompression flags.
+typedef struct {
+	Uint64  memlimit;   ///< Decoder memory usage limit
+	Boolean no_concat;  ///< Do not support concatenated xz streams
+	Boolean no_chk;     ///< Disregard data checksum during decoding
+	size_t  bufsiz;     ///< Input buffer size in bytes
+} XzDecOpts;
+
+/// LZMA operation status result.
+typedef int XzRet;  // 0 == OK
+
+/**
+ * \brief Implementation of the `StmOps` interface for LZMA streams.
+ *
+ * Allows any API working with streams to function with LZMA streams.
+ * `Xz_StmOps` implements the `Close()` method, while the non-closing
+ * `Xz_NcStmOps` leaves `Close()` to `NULL`, preventing any
+ * attempt to close the stream. Use this variant when such behavior is
+ * desirable (e.g. streams similar to `stdout` or `stdin`).
+ *
+ * @{
+ *   \var Xz_StmOps
+ *   \var Xz_NcStmOps
+ * @}
+ */
+extern const StmOps *const Xz_StmOps;
+extern const StmOps *const Xz_NcStmOps;
+
+/// Retrieve last operation's result status.
+XzRet Xz_GetErrStat(void);
+/// Convert `XzRet` to human readable string.
+const char *Xz_ErrorString(XzRet res);
+
+/**
+ * \brief Open stream for compression.
+ *
+ * \param [in,out] streamp Output stream for compressed LZMA data
+ * \param [in]     ops     Write operations interface for `streamp`, must not be `NULL` and provide `Write()`
+ * \param [in]     opts    Compression options, may be `NULL` for defaults
+ *
+ * \return The LZMA compressor handle on success, `NULL` on failure.
+ */
+XzStmHn Xz_OpenCompress(void *streamp, const StmOps *ops, const XzEncOpts *opts);
+/**
+ * \brief Open an LZMA stream for decompressing.
+ *
+ * \param [in,out] streamp Input stream for LZMA compressed data
+ * \param [in]     ops     Read operations interface for `streamp`, must not be `NULL` and provide `Read()`
+ * \param [in]     opts    Decompression options, may be `NULL` for defaults
+ *
+ * \return The LZMA decompressor handle on success, `NULL` on failure.
+ */
+XzStmHn Xz_OpenDecompress(void *streamp, const StmOps *ops, const XzDecOpts *opts);
+
+/**
+ * \brief Decompress `nbytes` bytes from `hn` into `buf`.
+ *
+ * \return Number of bytes actually written to `buf`, at most `nbytes`,
+ *         0 on end of stream, -1 on error.
+ */
+Sint64 Xz_Read(XzStmHn hn, void *buf, size_t nbytes);
+/**
+ * \brief Compresses `nbytes` bytes from `buf` to `hn`.
+ *
+ * \return Count of bytes actually compressed to `hn`, at most `nbytes`,
+ *         -1 on error.
+ *
+ * \note Compression should be finalized with `Xz_Finish()` once all
+ *       data is written.
+ */
+Sint64 Xz_Write(XzStmHn hn, const void *buf, size_t nbytes);
+
+/**
+ * \brief Finalize LZMA compression.
+ *
+ * \return `OK` on success, `NG` otherwise.
+ */
+Judgement Xz_Finish(XzStmHn hn);
+
+/// Close LZMA stream.
+void Xz_Close(XzStmHn hn);
+
+#endif