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