xz/src/liblzma/api/lzma/stream.h

/**
 * \file        lzma/stream.h
 * \brief       .lzma Stream 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 .lzma Stream encoder
 */
typedef struct {
	/**
	 * \brief       Type of integrity Check
	 *
	 * The type of the integrity Check is stored into Stream Header
	 * and Stream Footer. The same Check is used for all Blocks in
	 * the Stream.
	 */
	lzma_check_type check;

	/**
	 * \brief       Precense of CRC32 of the Block Header
	 *
	 * Set this to true if CRC32 of every Block Header should be
	 * calculated and stored in the Block Header. This is recommended.
	 *
	 * This setting is stored into Stream Header and Stream Footer.
	 */
	lzma_bool has_crc32;

	/**
	 * \brief       Uncompressed Size in bytes
	 *
	 * This is somewhat advanced feature. Most users want to set this to
	 * LZMA_VLI_VALUE_UNKNOWN to indicate unknown Uncompressed Size.
	 *
	 * If the Uncompressed Size of the Stream being encoded is known,
	 * it can be stored to the beginning of the Stream. The details
	 * differ for Single-Block and Multi-Block Streams:
	 *  - With Single-Block Streams, the Uncompressed Size is stored to
	 *    the Block Header and End of Payload Marker is omitted.
	 *  - With Multi-Block Streams, the Uncompressed Size is stored to
	 *    the Header Metadata Block. The Uncompressed Size of the Blocks
	 *    will be unknown, because liblzma cannot predict how the
	 *    application is going to split the data in Blocks.
	 */
	lzma_vli uncompressed_size;

	/**
	 * \brief       Alignment of the beginning of the Stream
	 *
	 * Certain filters handle data in bigger chunks than single bytes.
	 * This affects two things:
	 *   - Performance: aligned memory access is usually faster.
	 *   - Further compression ratio in custom file formats: if you
	 *     encode multiple Blocks with some non-compression filter
	 *     such as LZMA_FILTER_POWERPC, it is a good idea to keep
	 *     the inter-Block alignment correct to maximize compression
	 *     ratio when all these Blocks are finally compressed as a
	 *     single step.
	 *
	 * Usually the Stream is stored into its own file, thus
	 * the alignment is usually zero.
	 */
	uint32_t alignment;

	/**
	 * \brief       Array of filters used to encode Data Blocks
	 *
	 * There can be at maximum of seven filters. The end of the array is
	 * marked with .id = LZMA_VLI_VALUE_UNKNOWN. (That's why the array
	 * has eight members.) Minimum number of filters is zero; in that
	 * case, an implicit Copy filter is used.
	 */
	lzma_options_filter filters[8];

	/**
	 * \brief       Array of filters used to encode Metadata Blocks
	 *
	 * This is like filters[] but for Metadata Blocks. If Metadata
	 * Blocks are compressed, they usually are compressed with
	 * settings that require only little memory to uncompress e.g.
	 * LZMA with 64 KiB dictionary.
	 *
	 * \todo        Recommend a preset.
	 *
	 * When liblzma sees that the Metadata Block would be very small
	 * even in uncompressed form, it is not compressed no matter
	 * what filter have been set here. This is to avoid possibly
	 * increasing the size of the Metadata Block with bad compression,
	 * and to avoid useless overhead of filters in uncompression phase.
	 */
	lzma_options_filter metadata_filters[8];

	/**
	 * \brief       Extra information in the Header Metadata Block
	 */
	lzma_extra *header;

	/**
	 * \brief       Extra information in the Footer Metadata Block
	 *
	 * It is enough to set this pointer any time before calling
	 * lzma_code() with LZMA_FINISH as the second argument.
	 */
	lzma_extra *footer;

} lzma_options_stream;


/**
 * \brief       Initializes Single-Block .lzma Stream encoder
 *
 * This is the function that most developers are looking for. :-) It
 * compresses using the specified options without storing any extra
 * information.
 *
 * \todo        Describe that is_metadata is ignored, maybe something else.
 */
extern lzma_ret lzma_stream_encoder_single(
		lzma_stream *strm, const lzma_options_stream *options);


/**
 * \brief       Initializes Multi-Block .lzma Stream encoder
 *
 */
extern lzma_ret lzma_stream_encoder_multi(
		lzma_stream *strm, const lzma_options_stream *options);


/**
 * \brief       Initializes decoder for .lzma Stream
 *
 * \param       strm        Pointer to propertily prepared lzma_stream
 * \param       header      Pointer to hold a pointer to Extra Records read
 *                          from the Header Metadata Block. Use NULL if
 *                          you don't care about Extra Records.
 * \param       footer      Same as header, but for Footer Metadata Block.
 *
 * \return      - LZMA_OK: Initialization was successful.
 *              - LZMA_MEM_ERROR: Cannot allocate memory.
 *
 * If header and/or footer are not NULL, *header and/or *footer will be
 * initially set to NULL.
 *
 * The application can detect that Header Metadata Block has been completely
 * parsed when the decoder procudes some output the first time. If *header
 * is still NULL, there was no Extra field in the Header Metadata Block (or
 * the whole Header Metadata Block wasn't present at all).
 *
 * The application can detect that Footer Metadata Block has been parsed
 * completely when lzma_code() returns LZMA_STREAM_END. If *footer is still
 * NULL, there was no Extra field in the Footer Metadata Block.
 *
 * \note        If you use lzma_memory_limitter, the Extra Records will be
 *              allocated with it, and thus remain in the lzma_memory_limitter
 *              even after they get exported to the application via *header
 *              and *footer pointers.
 */
extern lzma_ret lzma_stream_decoder(lzma_stream *strm,
		lzma_extra **header, lzma_extra **footer);