/** * \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 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_limitter structure allocated and * initialized with lzma_memory_limitter_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 { 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);