Some API cleanups

[icculus/xz.git] / 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       Type of reserved enumeration variable in structures
 *
 * To avoid breaking library ABI when new features are added, several
 * structures contain extra variables that may be used in future. Since
 * sizeof(enum) can be different than sizeof(int), and sizeof(enum) may
 * even vary depending on the range of enumeration constants, we specify
 * a separate type to be used for reserved enumeration variables. All
 * enumeration constants in liblzma API will be non-negative and less
 * than 128, which should guarantee that the ABI won't break even when
 * new constants are added to existing enumerations.
 */
typedef enum {
        LZMA_RESERVED_ENUM      = 0
} lzma_reserved_enum;


/**
 * \brief       Return values used by several functions in liblzma
 *
 * Check the descriptions of specific functions to find out which return
 * values they can return. With some functions the return values may have
 * more specific meanings than described here; those differences are
 * described per-function basis.
 */
typedef enum {
        LZMA_OK                 = 0,
                /**<
                 * \brief       Operation completed successfully
                 */

        LZMA_STREAM_END         = 1,
                /**<
                 * \brief       End of stream was reached
                 *
                 * In encoder, LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, or
                 * LZMA_FINISH was finished. In decoder, this indicates
                 * that all the data was successfully decoded.
                 *
                 * In all cases, when LZMA_STREAM_END is returned, the last
                 * output bytes should be picked from strm->next_out.
                 */

        LZMA_NO_CHECK           = 2,
                /**<
                 * \brief       Input stream has no integrity check
                 *
                 * This return value can be returned only if the
                 * LZMA_TELL_NO_CHECK flag was used when initializing
                 * the decoder. LZMA_NO_CHECK is just a warning, and
                 * the decoding can be continued normally.
                 *
                 * It is possible to call lzma_get_check() immediatelly after
                 * lzma_code has returned LZMA_NO_CHECK. The result will
                 * naturally be LZMA_CHECK_NONE, but the possibility to call
                 * lzma_get_check() may be convenient in some applications.
                 */

        LZMA_UNSUPPORTED_CHECK  = 3,
                /**<
                 * \brief       Cannot calculate the integrity check
                 *
                 * The usage of this return value is slightly different in
                 * encoders and decoders.
                 *
                 * Encoders can return this value only from the initialization
                 * function. If initialization fails with this value, the
                 * encoding cannot be done, because there's no way to produce
                 * output with the correct integrity check.
                 *
                 * Decoders can return this value only from the lzma_code
                 * function and only if the LZMA_TELL_UNSUPPORTED_CHECK flag
                 * was used when initializing the decoder. The decoding can
                 * still be continued normally even if the check type is
                 * unsupported, but naturally the check will not be validated,
                 * and possible errors may go undetected.
                 *
                 * With decoder, it is possible to call lzma_get_check()
                 * immediatelly after lzma_code has returned
                 * LZMA_UNSUPPORTED_CHECK. This way it is possible to find
                 * out what the unsupported Check ID was.
                 */

        LZMA_GET_CHECK          = 4,
                /**<
                 * \brief       Integrity check type is now available
                 *
                 * This value can be returned only by the lzma_code() function
                 * and only if the decoder was initialized with the
                 * LZMA_TELL_ANY_CHECK flag. LZMA_GET_CHECK tells the
                 * application that it may now call lzma_get_check() to find
                 * out the Check ID. This can be used, for example, to
                 * implement a decoder that accepts only files that have
                 * strong enough integrity check.
                 */

        LZMA_MEM_ERROR          = 5,
                /**<
                 * \brief       Cannot allocate memory
                 *
                 * Memory allocation failed, or the size of the allocation
                 * would be greater than SIZE_MAX.
                 *
                 * Due to lazy coding, the coding cannot be continued even
                 * if more memory were made available after LZMA_MEM_ERROR.
                 */

        LZMA_MEMLIMIT_ERROR     = 6,
                /**
                 * \brief       Memory usage limit was reached
                 *
                 * Decoder would need more memory than allowed by the
                 * specified memory usage limit. To continue decoding,
                 * the memory usage limit has to be increased. See functions
                 * lzma_memlimit_get() and lzma_memlimit_set().
                 */

        LZMA_FORMAT_ERROR       = 7,
                /**<
                 * \brief       Unknown file format
                 *
                 * The decoder did not recognize the input as supported file
                 * format. This error can occur, for example, when trying to
                 * decode LZMA_Alone format file with lzma_stream_decoder,
                 * because lzma_stream_decoder accepts only the new .lzma
                 * format.
                 */

        LZMA_HEADER_ERROR       = 8,
                /**<
                 * \brief       Invalid or unsupported options
                 *
                 * 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_DATA_ERROR         = 9,
                /**<
                 * \brief       Data is corrupt
                 *
                 * The usage of this return value is different in encoders
                 * and decoders. In both encoder and decoder, the coding
                 * cannot continue after this error.
                 *
                 * Encoders return this if size limits of the target file
                 * format would be exceeded. These limits are huge, thus
                 * getting this error from an encoder is mostly theoretical.
                 * For example, the maximum compressed and uncompressed
                 * size of a Stream created with lzma_stream_encoder is
                 * 2^63 - 1 bytes (one byte less than 8 EiB).
                 *
                 * Decoders return this error if the input data is corrupt.
                 * This can mean, for example, invalid CRC32 in headers
                 * or invalid check of uncompressed data.
                 */

        LZMA_BUF_ERROR          = 10,
                /**<
                 * \brief       No progress is possible
                 *
                 * This error code is returned when the coder cannot consume
                 * any new input and produce any new output. The most common
                 * reason for this error is that the input stream being
                 * decoded is truncated or corrupt.
                 *
                 * This error is not fatal. Coding can be continued normally
                 * by providing more input and/or more output space, if
                 * possible.
                 *
                 * Typically the first call to lzma_code() that can do no
                 * progress returns LZMA_OK instead of LZMA_BUF_ERROR. Only
                 * the second consecutive call doing no progress will return
                 * LZMA_BUF_ERROR. This is by design.
                 *
                 * With zlib, Z_BUF_ERROR may be returned even if the
                 * application is doing nothing wrong. The above hack
                 * guarantees that liblzma never returns LZMA_BUF_ERROR
                 * to properly written applications unless the input file
                 * is truncated or corrupt. This should simplify the
                 * applications a little.
                 */

        LZMA_PROG_ERROR         = 11,
                /**<
                 * \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_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. Using LZMA_SYNC_FLUSH with
                 *              which such filters will make lzma_code()
                 *              return LZMA_HEADER_ERROR.
                 *
                 * Decoders don't support LZMA_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 Stream encoder and easy
                 * encoder (which uses Stream encoder). If there is no
                 * unfinished Block, no empty Block is created.
                 */

        LZMA_FINISH = 3
                /**<
                 * Finishes the coding 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. Once LZMA_FINISH has
                 * been used, the amount of input must no longer be changed
                 * by the application.
                 *
                 * When decoding, using LZMA_FINISH is optional unless the
                 * LZMA_CONCATENATED flag was used when the decoder was
                 * initialized. When LZMA_CONCATENATED was not used, the only
                 * effect of LZMA_FINISH is that the amount of input must not
                 * be changed just like in the encoder.
                 */
} lzma_action;


/**
 * \brief       Custom functions for memory handling
 *
 * A pointer to lzma_allocator may be passed via lzma_stream structure
 * to liblzma, and some advanced function take pointer lzma_allocator as
 * a separate function argument. The library will use the functions
 * specified in lzma_allocator 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
         *
         * 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.
         *
         * For performance reasons, the allocator should not waste time
         * zeroing the allocated buffers. This is not only about speed, but
         * also memory usage, since the operating system kernel doesn't
         * necessarily allocate the requested memory until it is actually
         * used. With small input files liblzma may actually need only a
         * fraction of the memory that it requested for allocation.
         *
         * \note        LZMA_MEM_ERROR is also used when the size of the
         *              allocation would be greater than SIZE_MAX. Thus,
         *              don't assume that the custom allocator must have
         *              returned NULL if some function from liblzma
         *              returns LZMA_MEM_ERROR.
         */
        void *(*alloc)(void *opaque, size_t nmemb, size_t size);

        /**
         * \brief       Pointer to custom memory freeing function
         *
         * 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.
         *
         * If you don't need this, you should set this 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.
 *
 * When a new lzma_stream structure is allocated (either as automatic variable
 * on stack or dynamically with malloc()), the new lzma_stream structure must
 * be initialized to LZMA_STREAM_INIT.
 *
 * Before initializing a coder (for example, with lzma_stream_decoder()),
 *
 *
 * 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 applications. */
        lzma_internal *internal;

        /**
         * Reserved space to allow possible future extensions without
         * breaking the ABI. Excluding the initialization of this structure,
         * you should not touch these, because the names of these variables
         * may change.
         */
        void *reserved_ptr1;
        void *reserved_ptr2;
        uint64_t reserved_int1;
        uint64_t reserved_int2;
        lzma_reserved_enum reserved_enum1;
        lzma_reserved_enum reserved_enum2;

} 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;
 *
 * If you need to initialize a dynamically allocated lzma_stream, you can use
 * memset(strm_pointer, 0, sizeof(lzma_stream)). Strictly speaking, this
 * violates the C standard since NULL may have different internal
 * representation than zero, but it should be portable enough in practice.
 * Anyway, for maximum portability, you can use something like this:
 *
 *     lzma_stream tmp = LZMA_STREAM_INIT;
 *     *strm = tmp;
 */
#define LZMA_STREAM_INIT \
        { NULL, 0, 0, NULL, 0, 0, NULL, NULL, NULL, NULL, 0, 0, 0, 0 }


/**
 * \brief       Encodes or decodes data
 *
 * Once the lzma_stream has been successfully initialized (e.g. with
 * lzma_stream_encoder()), the actual encoding or decoding is done
 * using this function. The application has to update strm->next_in,
 * strm->avail_in, strm->next_out, and strm->avail_out to pass input
 * to and get output from liblzma.
 *
 * See the description of the coder-specific initialization function to find
 * out what `action' values are supported by the coder. See documentation of
 * lzma_ret for the possible return values.
 */
extern lzma_ret lzma_code(lzma_stream *strm, lzma_action action)
                lzma_attr_warn_unused_result;


/**
 * \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);