/** * \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 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 */ const 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. */ const 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);