aboutsummaryrefslogtreecommitdiff
path: root/src/liblzma/api/lzma/base.h
diff options
context:
space:
mode:
authorLasse Collin <lasse.collin@tukaani.org>2007-12-09 00:42:33 +0200
committerLasse Collin <lasse.collin@tukaani.org>2007-12-09 00:42:33 +0200
commit5d018dc03549c1ee4958364712fb0c94e1bf2741 (patch)
tree1b211911fb33fddb3f04b77f99e81df23623ffc4 /src/liblzma/api/lzma/base.h
downloadxz-5d018dc03549c1ee4958364712fb0c94e1bf2741.tar.xz
Imported to git.
Diffstat (limited to '')
-rw-r--r--src/liblzma/api/lzma/base.h410
1 files changed, 410 insertions, 0 deletions
diff --git a/src/liblzma/api/lzma/base.h b/src/liblzma/api/lzma/base.h
new file mode 100644
index 00000000..53cf89f5
--- /dev/null
+++ b/src/liblzma/api/lzma/base.h
@@ -0,0 +1,410 @@
+/**
+ * \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 {
+ 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);