xz/src/liblzma/api/lzma/base.h

/**
 * \file        lzma/base.h
 * \brief       Data types and functions used in many places of the public API
 *
 * \author      Copyright (C) 1999-2006 Igor Pavlov
 * \author      Copyright (C) 2007 Lasse Collin
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 */

#ifndef LZMA_H_INTERNAL
#	error Never include this file directly. Use <lzma.h> instead.
#endif


/**
 * \brief       Boolean
 *
 * This is here because C89 doesn't have stdbool.h. To set a value for
 * variables having type lzma_bool, you can use
 *   - C99's `true' and `false' from stdbool.h;
 *   - C++'s internal `true' and `false'; or
 *   - integers one (true) and zero (false).
 */
typedef unsigned char lzma_bool;


/**
 * \brief       Return values used by several functions in liblzma
 *
 * Check the descriptions of specific functions to find out which return
 * values they can return and the exact meanings of the values in every
 * situation. The descriptions given here are only suggestive.
 */
typedef enum {
	LZMA_OK                 =  0,
		/**<
		 * \brief       Operation completed successfully
		 */

	LZMA_STREAM_END         =  1,
		/**<
		 * \brief       End of stream was reached
		 *
		 * The application should pick the last remaining output
		 * bytes from strm->next_out.
		 */

	LZMA_PROG_ERROR       = -2,
		/**<
		 * \brief       Programming error
		 *
		 * This indicates that the arguments given to the function are
		 * invalid or the internal state of the decoder is corrupt.
		 *   - Function arguments are invalid or the structures
		 *     pointed by the argument pointers are invalid
		 *     e.g. if strm->next_out has been set to NULL and
		 *     strm->avail_out > 0 when calling lzma_code().
		 *   - lzma_* functions have been called in wrong order
		 *     e.g. lzma_code() was called right after lzma_end().
		 *   - If errors occur randomly, the reason might be flaky
		 *     hardware.
		 *
		 * If you think that your code is correct, this error code
		 * can be a sign of a bug in liblzma. See the documentation
		 * how to report bugs.
		 */

	LZMA_DATA_ERROR         = -3,
		/**<
		 * \brief       Data is corrupt
		 *
		 * - Encoder: The input size doesn't match the uncompressed
		 *   size given to lzma_*_encoder_init().
		 * - Decoder: The input is corrupt. This includes corrupted
		 *   header, corrupted compressed data, and unmatching
		 *   integrity Check.
		 *
		 * \todo        What can be done if encoder returns this?
		 *              Probably can continue by fixing the input
		 *              amount, but make sure.
		 */

	LZMA_MEM_ERROR          = -4,
		/**<
		 * \brief       Cannot allocate memory
		 *
		 * Memory allocation failed.
		 */

	LZMA_BUF_ERROR          = -5,
		/**<
		 * \brief       No progress is possible
		 *
		 * This may happen when avail_in or avail_out is zero.
		 *
		 * \note        This error is not fatal. Coding can continue
		 *              normally once the reason for this error has
		 *              been fixed.
		 */

	LZMA_HEADER_ERROR       = -6,
		/**<
		 * \brief       Invalid or unsupported header
		 *
		 * Invalid or unsupported options, for example
		 *  - unsupported filter(s) or filter options; or
		 *  - reserved bits set in headers (decoder only).
		 *
		 * Rebuilding liblzma with more features enabled, or
		 * upgrading to a newer version of liblzma may help.
		 */

	LZMA_UNSUPPORTED_CHECK  = -7,
		/**<
		 * \brief       Check type is unknown
		 *
		 * The type of Check is not supported, and thus the Check
		 * cannot be calculated. In the encoder, this is an error.
		 * In the decoder, this is only a warning and decoding can
		 * still proceed normally (but the Check is ignored).
		 */
} lzma_ret;


/**
 * \brief       The `action' argument for lzma_code()
 */
typedef enum {
	LZMA_RUN = 0,
		/**<
		 * Encoder: Encode as much input as possible. Some internal
		 * buffering will probably be done (depends on the filter
		 * chain in use), which causes latency: the input used won't
		 * usually be decodeable from the output of the same
		 * lzma_code() call.
		 *
		 * Decoder: Decode as much input as possible and produce as
		 * much output as possible. This action provides best
		 * throughput, but may introduce latency, because the
		 * decoder may decode more data into its internal buffers
		 * than that fits into next_out.
		 */

	LZMA_SYNC_FLUSH = 1,
		/**<
		 * Encoder: Makes all the data given to liblzma via next_in
		 * available in next_out without resetting the filters. Call
		 * lzma_code() with LZMA_SYNC_FLUSH until it returns
		 * LZMA_STREAM_END. Then continue encoding normally.
		 *
		 * \note        Synchronous flushing is supported only by
		 *              some filters. Some filters support it only
		 *              partially.
		 *
		 * Decoder: Asks the decoder to decode only as much as is
		 * needed to fill next_out. This decreases latency with some
		 * filters, but is likely to decrease also throughput. It is
		 * a good idea to use this flag only when it is likely that
		 * you don't need more output soon.
		 *
		 * \note        With decoder, this is not comparable to
		 *              zlib's Z_SYNC_FLUSH.
		 */

	LZMA_FULL_FLUSH = 2,
		/**<
		 * Finishes encoding of the current Data Block. All the input
		 * data going to the current Data Block must have been given
		 * to the encoder (the last bytes can still be pending in
		 * next_in). Call lzma_code() with LZMA_FULL_FLUSH until
		 * it returns LZMA_STREAM_END. Then continue normally with
		 * LZMA_RUN or finish the Stream with LZMA_FINISH.
		 *
		 * This action is supported only by Multi-Block Stream
		 * encoder. If there is no unfinished Data Block, no empty
		 * Data Block is created.
		 */

	LZMA_FINISH = 3
		/**<
		 * Finishes the encoding operation. All the input data must
		 * have been given to the encoder (the last bytes can still
		 * be pending in next_in). Call lzma_code() with LZMA_FINISH
		 * until it returns LZMA_STREAM_END.
		 *
		 * This action is not supported by decoders.
		 */
} lzma_action;


/**
 * \brief       Custom functions for memory handling
 *
 * A pointer to lzma_allocator may be passed via lzma_stream structure
 * to liblzma. The library will use these functions for memory handling
 * instead of the default malloc() and free().
 *
 * liblzma doesn't make an internal copy of lzma_allocator. Thus, it is
 * OK to change these function pointers in the middle of the coding
 * process, but obviously it must be done carefully to make sure that the
 * replacement `free' can deallocate memory allocated by the earlier
 * `alloc' function(s).
 */
typedef struct {
	/**
	 * \brief       Pointer to custom memory allocation function
	 *
	 * Set this to point to your custom memory allocation function.
	 * It can be useful for example if you want to limit how much
	 * memory liblzma is allowed to use: for this, you may use
	 * a pointer to lzma_memory_alloc().
	 *
	 * If you don't want a custom allocator, but still want
	 * custom free(), set this to NULL and liblzma will use
	 * the standard malloc().
	 *
	 * \param       opaque  lzma_allocator.opaque (see below)
	 * \param       nmemb   Number of elements like in calloc().
	 *                      liblzma will always set nmemb to 1.
	 *                      This argument exists only for
	 *                      compatibility with zlib and libbzip2.
	 * \param       size    Size of an element in bytes.
	 *                      liblzma never sets this to zero.
	 *
	 * \return      Pointer to the beginning of a memory block of
	 *              size nmemb * size, or NULL if allocation fails
	 *              for some reason. When allocation fails, functions
	 *              of liblzma return LZMA_MEM_ERROR.
	 */
	void *(*alloc)(void *opaque, size_t nmemb, size_t size);

	/**
	 * \brief       Pointer to custom memory freeing function
	 *
	 * Set this to point to your custom memory freeing function.
	 * If lzma_memory_alloc() is used as allocator, this should
	 * be set to lzma_memory_free().
	 *
	 * If you don't want a custom freeing function, but still
	 * want a custom allocator, set this to NULL and liblzma
	 * will use the standard free().
	 *
	 * \param       opaque  lzma_allocator.opaque (see below)
	 * \param       ptr     Pointer returned by
	 *                      lzma_allocator.alloc(), or when it
	 *                      is set to NULL, a pointer returned
	 *                      by the standard malloc().
	 */
	void (*free)(void *opaque, void *ptr);

	/**
	 * \brief       Pointer passed to .alloc() and .free()
	 *
	 * opaque is passed as the first argument to lzma_allocator.alloc()
	 * and lzma_allocator.free(). This intended to ease implementing
	 * custom memory allocation functions for use with liblzma.
	 *
	 * When using lzma_memory_alloc() and lzma_memory_free(), opaque
	 * must point to lzma_memory_limiter structure allocated and
	 * initialized with lzma_memory_limiter_create().
	 *
	 * If you don't need this, you should set it to NULL.
	 */
	void *opaque;

} lzma_allocator;


/**
 * \brief       Internal data structure
 *
 * The contents of this structure is not visible outside the library.
 */
typedef struct lzma_internal_s lzma_internal;


/**
 * \brief       Passing data to and from liblzma
 *
 * The lzma_stream structure is used for
 *   - passing pointers to input and output buffers to liblzma;
 *   - defining custom memory hander functions; and
 *   - holding a pointer to coder-specific internal data structures.
 *
 * Before calling any of the lzma_*_init() functions the first time,
 * the application must reset lzma_stream to LZMA_STREAM_INIT. The
 * lzma_*_init() function will verify the options, allocate internal
 * data structures and store pointer to them into `internal'. Finally
 * total_in and total_out are reset to zero. In contrast to zlib,
 * next_in and avail_in are ignored by the initialization functions.
 *
 * The actual coding is done with the lzma_code() function. Application
 * must update next_in, avail_in, next_out, and avail_out between
 * calls to lzma_decode() just like with zlib.
 *
 * In contrast to zlib, even the decoder requires that there always
 * is at least one byte space in next_out; if avail_out == 0,
 * LZMA_BUF_ERROR is returned immediatelly. This shouldn't be a problem
 * for most applications that already use zlib, but it's still worth
 * checking your application.
 *
 * Application may modify values of total_in and total_out as it wants.
 * They are updated by liblzma to match the amount of data read and
 * written, but liblzma doesn't use the values internally.
 *
 * Application must not touch the `internal' pointer.
 */
typedef struct {
	const uint8_t *next_in; /**< Pointer to the next input byte. */
	size_t avail_in;    /**< Number of available input bytes in next_in. */
	uint64_t total_in;  /**< Total number of bytes read by liblzma. */

	uint8_t *next_out;  /**< Pointer to the next output position. */
	size_t avail_out;   /**< Amount of free space in next_out. */
	uint64_t total_out; /**< Total number of bytes written by liblzma. */

	/**
	 * Custom memory allocation functions. Set to NULL to use
	 * the standard malloc() and free().
	 */
	lzma_allocator *allocator;

	/** Internal state is not visible to outsiders. */
	lzma_internal *internal;

} lzma_stream;


/**
 * \brief       Initialization for lzma_stream
 *
 * When you declare an instance of lzma_stream, you can immediatelly
 * initialize it so that initialization functions know that no memory
 * has been allocated yet:
 *
 *     lzma_stream strm = LZMA_STREAM_INIT;
 */
#define LZMA_STREAM_INIT { NULL, 0, 0, NULL, 0, 0, NULL, NULL }


/**
 * \brief       Initialization for lzma_stream
 *
 * This is like LZMA_STREAM_INIT, but this can be used when the lzma_stream
 * has already been allocated:
 *
 *     lzma_stream *strm = malloc(sizeof(lzma_stream));
 *     if (strm == NULL)
 *         return LZMA_MEM_ERROR;
 *     *strm = LZMA_STREAM_INIT_VAR;
 */
extern const lzma_stream LZMA_STREAM_INIT_VAR;


/**
 * \brief       Encodes or decodes data
 *
 * Once the lzma_stream has been successfully initialized (e.g. with
 * lzma_stream_encoder_single()), the actual encoding or decoding is
 * done using this function.
 *
 * \return      Some coders may have more exact meaning for different return
 *              values, which are mentioned separately in the description of
 *              the initialization functions. Here are the typical meanings:
 *              - LZMA_OK: So far all good.
 *              - LZMA_STREAM_END:
 *                  - Encoder: LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, or
 *                    LZMA_FINISH completed.
 *                  - Decoder: End of uncompressed data was reached.
 *              - LZMA_BUF_ERROR: Unable to progress. Provide more input or
 *                output space, and call this function again. This cannot
 *                occur if both avail_in and avail_out were non-zero (or
 *                there's a bug in liblzma).
 *              - LZMA_MEM_ERROR: Unable to allocate memory. Due to lazy
 *                programming, the coding cannot continue even if the
 *                application could free more memory. The next call must
 *                be lzma_end() or some initialization function.
 *              - LZMA_DATA_ERROR:
 *                  - Encoder: Filter(s) cannot process the given data.
 *                  - Decoder: Compressed data is corrupt.
 *              - LZMA_HEADER_ERROR: Unsupported options. Rebuilding liblzma
 *                with more features enabled or upgrading to a newer version
 *                may help, although usually this is a sign of invalid options
 *                (encoder) or corrupted input data (decoder).
 *              - LZMA_PROG_ERROR: Invalid arguments or the internal state
 *                of the coder is corrupt.
 */
extern lzma_ret lzma_code(lzma_stream *strm, lzma_action action);


/**
 * \brief       Frees memory allocated for the coder data structures
 *
 * \param       strm    Pointer to lzma_stream that is at least initialized
 *                      with LZMA_STREAM_INIT.
 *
 * \note        zlib indicates an error if application end()s unfinished
 *              stream. liblzma doesn't do this, and assumes that
 *              application knows what it is doing.
 */
extern void lzma_end(lzma_stream *strm);