aboutsummaryrefslogtreecommitdiff
path: root/src/liblzma/api/lzma/block.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/block.h
downloadxz-5d018dc03549c1ee4958364712fb0c94e1bf2741.tar.xz
Imported to git.
Diffstat (limited to 'src/liblzma/api/lzma/block.h')
-rw-r--r--src/liblzma/api/lzma/block.h409
1 files changed, 409 insertions, 0 deletions
diff --git a/src/liblzma/api/lzma/block.h b/src/liblzma/api/lzma/block.h
new file mode 100644
index 00000000..210c1d87
--- /dev/null
+++ b/src/liblzma/api/lzma/block.h
@@ -0,0 +1,409 @@
+/**
+ * \file lzma/block.h
+ * \brief .lzma Block handling
+ *
+ * \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 Options for the Block Header encoder and decoder
+ *
+ * Different things use different parts of this structure. Some read
+ * some members, other functions write, and some do both. Only the
+ * members listed for reading need to be initialized when the specified
+ * functions are called. The members marked for writing will be assigned
+ * new values at some point either by calling the given function or by
+ * later calls to lzma_code().
+ */
+typedef struct {
+ /**
+ * \brief Type of integrity Check
+ *
+ * The type of the integrity Check is not stored into the Block
+ * Header, thus its value must be provided also when decoding.
+ *
+ * Read by:
+ * - lzma_block_encoder()
+ * - lzma_block_decoder()
+ */
+ lzma_check_type check;
+
+ /**
+ * \brief Precense of CRC32 of the Block Header
+ *
+ * Set this to true if CRC32 of the Block Header should be
+ * calculated and stored in the Block Header.
+ *
+ * There is no way to autodetect if CRC32 is present in the Block
+ * Header, thus this information must be provided also when decoding.
+ *
+ * Read by:
+ * - lzma_block_header_size()
+ * - lzma_block_header_encoder()
+ * - lzma_block_header_decoder()
+ */
+ lzma_bool has_crc32;
+
+ /**
+ * \brief Usage of End of Payload Marker
+ *
+ * If this is true, End of Payload Marker is used even if
+ * Uncompressed Size is known.
+ *
+ * Read by:
+ * - lzma_block_header_encoder()
+ * - lzma_block_encoder()
+ * - lzma_block_decoder()
+ *
+ * Written by:
+ * - lzma_block_header_decoder()
+ */
+ lzma_bool has_eopm;
+
+ /**
+ * \brief True if the Block is a Metadata Block
+ *
+ * If this is true, the Metadata bit will be set in the Block Header.
+ * It is up to the application to store correctly formatted data
+ * into Metadata Block.
+ *
+ * Read by:
+ * - lzma_block_header_encoder()
+ *
+ * Written by:
+ * - lzma_block_header_decoder()
+ */
+ lzma_bool is_metadata;
+
+ /**
+ * \brief True if Uncompressed Size is in Block Footer
+ *
+ * Read by:
+ * - lzma_block_encoder()
+ * - lzma_block_decoder()
+ */
+ lzma_bool has_uncompressed_size_in_footer;
+
+ /**
+ * \brief True if Backward Size is in Block Footer
+ *
+ * Read by:
+ * - lzma_block_encoder()
+ * - lzma_block_decoder()
+ */
+ lzma_bool has_backward_size;
+
+ /**
+ * \brief True if Block coder should take care of Padding
+ *
+ * In liblzma, Stream decoder sets this to true when decoding
+ * Header Metadata Block or Data Blocks from Multi-Block Stream,
+ * and to false when decoding Single-Block Stream or Footer
+ * Metadata Block from a Multi-Block Stream.
+ *
+ * Read by:
+ * - lzma_block_encoder()
+ * - lzma_block_decoder()
+ */
+ lzma_bool handle_padding;
+
+ /**
+ * \brief Size of the Compressed Data in bytes
+ *
+ * Usually you don't know this value when encoding in streamed mode.
+ * In non-streamed mode you can reserve space for this field when
+ * encoding the Block Header the first time, and then re-encode the
+ * Block Header and copy it over the original one after the encoding
+ * of the Block has been finished.
+ *
+ * Read by:
+ * - lzma_block_header_size()
+ * - lzma_block_header_encoder()
+ * - lzma_block_encoder()
+ * - lzma_block_decoder()
+ *
+ * Written by:
+ * - lzma_block_header_decoder()
+ * - lzma_block_encoder()
+ * - lzma_block_decoder()
+ */
+ lzma_vli compressed_size;
+
+ /**
+ * \brief Uncompressed Size in bytes
+ *
+ * Encoder: If this value is not LZMA_VLI_VALUE_UNKNOWN, it is stored
+ * to the Uncompressed Size field in the Block Header. The real
+ * uncompressed size of the data being compressed must match
+ * the Uncompressed Size or LZMA_HEADER_ERROR is returned.
+ *
+ * If Uncompressed Size is unknown, End of Payload Marker must
+ * be used. If uncompressed_size == LZMA_VLI_VALUE_UNKNOWN and
+ * has_eopm == 0, LZMA_HEADER_ERROR will be returned.
+ *
+ * Decoder: If this value is not LZMA_VLI_VALUE_UNKNOWN, it is
+ * compared to the real Uncompressed Size. If they do not match,
+ * LZMA_HEADER_ERROR is returned.
+ *
+ * Read by:
+ * - lzma_block_header_size()
+ * - lzma_block_header_encoder()
+ * - lzma_block_encoder()
+ * - lzma_block_decoder()
+ *
+ * Written by:
+ * - lzma_block_header_decoder()
+ * - lzma_block_encoder()
+ * - lzma_block_decoder()
+ */
+ lzma_vli uncompressed_size;
+
+ /**
+ * \brief Number of bytes to reserve for Compressed Size
+ *
+ * This is useful if you want to be able to store the Compressed Size
+ * to the Block Header, but you don't know it when starting to encode.
+ * Setting this to non-zero value at maximum of LZMA_VLI_BYTES_MAX,
+ * the Block Header encoder will force the Compressed Size field to
+ * occupy specified number of bytes. You can later rewrite the Block
+ * Header to contain correct information by using otherwise identical
+ * lzma_options_block structure except the correct compressed_size.
+ *
+ * Read by:
+ * - lzma_block_header_size()
+ * - lzma_block_header_encoder()
+ *
+ * Written by:
+ * - lzma_block_header_decoder()
+ */
+ uint32_t compressed_reserve;
+
+ /**
+ * \brief Number of bytes to reserve for Uncompressed Size
+ *
+ * See the description of compressed_size above.
+ *
+ * Read by:
+ * - lzma_block_header_size()
+ * - lzma_block_header_encoder()
+ *
+ * Written by:
+ * - lzma_block_header_decoder()
+ */
+ uint32_t uncompressed_reserve;
+
+ /**
+ * \brief Total Size of the Block in bytes
+ *
+ * This is useful in the decoder, which can verify the Total Size
+ * if it is known from Index.
+ *
+ * Read by:
+ * - lzma_block_encoder()
+ * - lzma_block_decoder()
+ *
+ * Written by:
+ * - lzma_block_encoder()
+ * - lzma_block_decoder()
+ */
+ lzma_vli total_size;
+
+ /**
+ * \brief Upper limit of Total Size
+ *
+ * Read by:
+ * - lzma_block_encoder()
+ * - lzma_block_decoder()
+ */
+ lzma_vli total_limit;
+
+ /**
+ * \brief Upper limit of Uncompressed Size
+ *
+ * Read by:
+ * - lzma_block_encoder()
+ * - lzma_block_decoder()
+ */
+ lzma_vli uncompressed_limit;
+
+ /**
+ * \brief Array of filters
+ *
+ * There can be at maximum of seven filters. The end of the array
+ * is marked with .id = LZMA_VLI_VALUE_UNKNOWN. Minimum number of
+ * filters is zero; in that case, an implicit Copy filter is used.
+ *
+ * Read by:
+ * - lzma_block_header_size()
+ * - lzma_block_header_encoder()
+ * - lzma_block_encoder()
+ * - lzma_block_decoder()
+ *
+ * Written by:
+ * - lzma_block_header_decoder(): Note that this does NOT free()
+ * the old filter options structures. If decoding fails, the
+ * caller must take care of freeing the options structures
+ * that may have been allocated and decoded before the error
+ * occurred.
+ */
+ lzma_options_filter filters[8];
+
+ /**
+ * \brief Size of the Padding field
+ *
+ * The Padding field exist to allow aligning the Compressed Data field
+ * optimally in the Block. See lzma_options_stream.alignment in
+ * stream.h for more information.
+ *
+ * If you want the Block Header encoder to automatically calculate
+ * optimal size for the Padding field by looking at the information
+ * in filters[], set this to LZMA_BLOCK_HEADER_PADDING_AUTO. In that
+ * case, you must also set the aligmnet variable to tell the the
+ * encoder the aligmnet of the beginning of the Block Header.
+ *
+ * The decoder never sets this to LZMA_BLOCK_HEADER_PADDING_AUTO.
+ *
+ * Read by:
+ * - lzma_block_header_size()
+ * - lzma_block_header_encoder(): Note that this doesn't
+ * accept LZMA_BLOCK_HEADER_PADDING_AUTO.
+ *
+ * Written by (these never set padding to
+ * LZMA_BLOCK_HEADER_PADDING_AUTO):
+ * - lzma_block_header_size()
+ * - lzma_block_header_decoder()
+ */
+ int32_t padding;
+# define LZMA_BLOCK_HEADER_PADDING_AUTO (-1)
+# define LZMA_BLOCK_HEADER_PADDING_MIN 0
+# define LZMA_BLOCK_HEADER_PADDING_MAX 31
+
+ /**
+ * \brief Alignment of the beginning of the Block Header
+ *
+ * This variable is read only if padding has been set to
+ * LZMA_BLOCK_HEADER_PADDING_AUTO.
+ *
+ * Read by:
+ * - lzma_block_header_size()
+ * - lzma_block_header_encoder()
+ */
+ uint32_t alignment;
+
+ /**
+ * \brief Size of the Block Header
+ *
+ * Read by:
+ * - lzma_block_encoder()
+ * - lzma_block_decoder()
+ *
+ * Written by:
+ * - lzma_block_header_size()
+ * - lzma_block_header_decoder()
+ */
+ uint32_t header_size;
+
+} lzma_options_block;
+
+
+/**
+ * \brief Calculates the size of Header Padding and Block Header
+ *
+ * \return - LZMA_OK: Size calculated successfully and stored to
+ * options->header_size.
+ * - LZMA_HEADER_ERROR: Unsupported filters or filter options.
+ * - LZMA_PROG_ERROR: Invalid options
+ *
+ * \note This doesn't check that all the options are valid i.e. this
+ * may return LZMA_OK even if lzma_block_header_encode() or
+ * lzma_block_encoder() would fail.
+ */
+extern lzma_ret lzma_block_header_size(lzma_options_block *options);
+
+
+/**
+ * \brief Encodes Block Header
+ *
+ * Encoding of the Block options is done with a single call instead of
+ * first initializing and then doing the actual work with lzma_code().
+ *
+ * \param out Beginning of the output buffer. This must be
+ * at least options->header_size bytes.
+ * \param options Block options to be encoded.
+ *
+ * \return - LZMA_OK: Encoding was successful. options->header_size
+ * bytes were written to output buffer.
+ * - LZMA_HEADER_ERROR: Invalid or unsupported options.
+ * - LZMA_PROG_ERROR
+ */
+extern lzma_ret lzma_block_header_encode(
+ uint8_t *out, const lzma_options_block *options);
+
+
+/**
+ * \brief Initializes Block Header decoder
+ *
+ * Because the results of this decoder are placed into *options,
+ * strm->next_in, strm->avail_in, and strm->total_in are not used.
+ *
+ * The only valid `action' with lzma_code() is LZMA_RUN.
+ *
+ * \return - LZMA_OK: Encoding was successful. options->header_size
+ * bytes were written to output buffer.
+ * - LZMA_HEADER_ERROR: Invalid or unsupported options.
+ * - LZMA_PROG_ERROR
+ */
+extern lzma_ret lzma_block_header_decoder(
+ lzma_stream *strm, lzma_options_block *options);
+
+
+/**
+ * \brief Initializes .lzma Block encoder
+ *
+ * This function is required for multi-thread encoding. It may also be
+ * useful when implementing custom file formats.
+ *
+ * \return - LZMA_OK: All good, continue with lzma_code().
+ * - LZMA_MEM_ERROR
+ * - LZMA_HEADER_ERROR
+ * - LZMA_DATA_ERROR: Limits (total_limit and uncompressed_limit)
+ * have been reached already.
+ * - LZMA_UNSUPPORTED_CHECK: options->check specfies a Check
+ * that is not supported by this buid of liblzma. Initializing
+ * the encoder failed.
+ * - LZMA_PROG_ERROR
+ *
+ * lzma_code() can return FIXME
+ */
+extern lzma_ret lzma_block_encoder(
+ lzma_stream *strm, lzma_options_block *options);
+
+
+/**
+ * \brief Initializes decoder for .lzma Block
+ *
+ * \return - LZMA_OK: All good, continue with lzma_code().
+ * - LZMA_UNSUPPORTED_CHECK: Initialization was successful, but
+ * the given Check type is not supported, thus Check will be
+ * ignored.
+ * - LZMA_PROG_ERROR
+ * - LZMA_MEM_ERROR
+ */
+extern lzma_ret lzma_block_decoder(
+ lzma_stream *strm, lzma_options_block *options);