3 * \brief .lzma Stream handling
5 * \author Copyright (C) 1999-2006 Igor Pavlov
6 * \author Copyright (C) 2007 Lasse Collin
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2.1 of the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
19 #ifndef LZMA_H_INTERNAL
20 # error Never include this file directly. Use <lzma.h> instead.
25 * \brief Options for .lzma Stream encoder
29 * \brief Type of integrity Check
31 * The type of the integrity Check is stored into Stream Header
32 * and Stream Footer. The same Check is used for all Blocks in
35 lzma_check_type check;
38 * \brief Precense of CRC32 of the Block Header
40 * Set this to true if CRC32 of every Block Header should be
41 * calculated and stored in the Block Header. This is recommended.
43 * This setting is stored into Stream Header and Stream Footer.
48 * \brief Uncompressed Size in bytes
50 * This is somewhat advanced feature. Most users want to set this to
51 * LZMA_VLI_VALUE_UNKNOWN to indicate unknown Uncompressed Size.
53 * If the Uncompressed Size of the Stream being encoded is known,
54 * it can be stored to the beginning of the Stream. The details
55 * differ for Single-Block and Multi-Block Streams:
56 * - With Single-Block Streams, the Uncompressed Size is stored to
57 * the Block Header and End of Payload Marker is omitted.
58 * - With Multi-Block Streams, the Uncompressed Size is stored to
59 * the Header Metadata Block. The Uncompressed Size of the Blocks
60 * will be unknown, because liblzma cannot predict how the
61 * application is going to split the data in Blocks.
63 lzma_vli uncompressed_size;
66 * \brief Alignment of the beginning of the Stream
68 * Certain filters handle data in bigger chunks than single bytes.
69 * This affects two things:
70 * - Performance: aligned memory access is usually faster.
71 * - Further compression ratio in custom file formats: if you
72 * encode multiple Blocks with some non-compression filter
73 * such as LZMA_FILTER_POWERPC, it is a good idea to keep
74 * the inter-Block alignment correct to maximize compression
75 * ratio when all these Blocks are finally compressed as a
78 * Usually the Stream is stored into its own file, thus
79 * the alignment is usually zero.
84 * \brief Array of filters used to encode Data Blocks
86 * There can be at maximum of seven filters. The end of the array is
87 * marked with .id = LZMA_VLI_VALUE_UNKNOWN. (That's why the array
88 * has eight members.) Minimum number of filters is zero; in that
89 * case, an implicit Copy filter is used.
91 lzma_options_filter filters[8];
94 * \brief Array of filters used to encode Metadata Blocks
96 * This is like filters[] but for Metadata Blocks. If Metadata
97 * Blocks are compressed, they usually are compressed with
98 * settings that require only little memory to uncompress e.g.
99 * LZMA with 64 KiB dictionary.
101 * \todo Recommend a preset.
103 * When liblzma sees that the Metadata Block would be very small
104 * even in uncompressed form, it is not compressed no matter
105 * what filter have been set here. This is to avoid possibly
106 * increasing the size of the Metadata Block with bad compression,
107 * and to avoid useless overhead of filters in uncompression phase.
109 lzma_options_filter metadata_filters[8];
112 * \brief Extra information in the Header Metadata Block
114 const lzma_extra *header;
117 * \brief Extra information in the Footer Metadata Block
119 * It is enough to set this pointer any time before calling
120 * lzma_code() with LZMA_FINISH as the second argument.
122 const lzma_extra *footer;
124 } lzma_options_stream;
128 * \brief Initializes Single-Block .lzma Stream encoder
130 * This is the function that most developers are looking for. :-) It
131 * compresses using the specified options without storing any extra
134 * \todo Describe that is_metadata is ignored, maybe something else.
136 extern lzma_ret lzma_stream_encoder_single(
137 lzma_stream *strm, const lzma_options_stream *options);
141 * \brief Initializes Multi-Block .lzma Stream encoder
144 extern lzma_ret lzma_stream_encoder_multi(
145 lzma_stream *strm, const lzma_options_stream *options);
149 * \brief Initializes decoder for .lzma Stream
151 * \param strm Pointer to propertily prepared lzma_stream
152 * \param header Pointer to hold a pointer to Extra Records read
153 * from the Header Metadata Block. Use NULL if
154 * you don't care about Extra Records.
155 * \param footer Same as header, but for Footer Metadata Block.
157 * \return - LZMA_OK: Initialization was successful.
158 * - LZMA_MEM_ERROR: Cannot allocate memory.
160 * If header and/or footer are not NULL, *header and/or *footer will be
161 * initially set to NULL.
163 * The application can detect that Header Metadata Block has been completely
164 * parsed when the decoder procudes some output the first time. If *header
165 * is still NULL, there was no Extra field in the Header Metadata Block (or
166 * the whole Header Metadata Block wasn't present at all).
168 * The application can detect that Footer Metadata Block has been parsed
169 * completely when lzma_code() returns LZMA_STREAM_END. If *footer is still
170 * NULL, there was no Extra field in the Footer Metadata Block.
172 * \note If you use lzma_memory_limitter, the Extra Records will be
173 * allocated with it, and thus remain in the lzma_memory_limitter
174 * even after they get exported to the application via *header
175 * and *footer pointers.
177 extern lzma_ret lzma_stream_decoder(lzma_stream *strm,
178 lzma_extra **header, lzma_extra **footer);