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