]> icculus.org git repositories - icculus/xz.git/blob - src/liblzma/api/lzma/block.h
Cleaned up Block encoder and moved the no longer shared
[icculus/xz.git] / src / liblzma / api / lzma / block.h
1 /**
2  * \file        lzma/block.h
3  * \brief       .lzma Block handling
4  *
5  * \author      Copyright (C) 1999-2006 Igor Pavlov
6  * \author      Copyright (C) 2007 Lasse Collin
7  *
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.
12  *
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.
17  */
18
19 #ifndef LZMA_H_INTERNAL
20 #       error Never include this file directly. Use <lzma.h> instead.
21 #endif
22
23
24 /**
25  * \brief       Options for the Block Header encoder and decoder
26  *
27  * Different things use different parts of this structure. Some read
28  * some members, other functions write, and some do both. Only the
29  * members listed for reading need to be initialized when the specified
30  * functions are called. The members marked for writing will be assigned
31  * new values at some point either by calling the given function or by
32  * later calls to lzma_code().
33  */
34 typedef struct {
35         /**
36          * \brief       Size of the Block Header
37          *
38          * Read by:
39          *  - lzma_block_header_encode()
40          *  - lzma_block_header_decode()
41          *  - lzma_block_decoder()
42          *
43          * Written by:
44          *  - lzma_block_header_size()
45          */
46         uint32_t header_size;
47 #       define LZMA_BLOCK_HEADER_SIZE_MIN 8
48 #       define LZMA_BLOCK_HEADER_SIZE_MAX 1024
49
50         /**
51          * \brief       Type of integrity Check
52          *
53          * The type of the integrity Check is not stored into the Block
54          * Header, thus its value must be provided also when decoding.
55          *
56          * Read by:
57          *  - lzma_block_header_encode()
58          *  - lzma_block_header_decode()
59          *  - lzma_block_encoder()
60          *  - lzma_block_decoder()
61          */
62         lzma_check check;
63
64         /**
65          * \brief       Size of the Compressed Data in bytes
66          *
67          * Usually you don't know this value when encoding in streamed mode.
68          * In non-streamed mode you can reserve space for this field when
69          * encoding the Block Header the first time, and then re-encode the
70          * Block Header and copy it over the original one after the encoding
71          * of the Block has been finished.
72          *
73          * Read by:
74          *  - lzma_block_header_size()
75          *  - lzma_block_header_encode()
76          *  - lzma_block_decoder()
77          *
78          * Written by:
79          *  - lzma_block_header_decode()
80          *  - lzma_block_encoder()
81          *  - lzma_block_decoder()
82          */
83         lzma_vli compressed_size;
84
85         /**
86          * \brief       Uncompressed Size in bytes
87          *
88          * Encoder: If this value is not LZMA_VLI_VALUE_UNKNOWN, it is stored
89          * to the Uncompressed Size field in the Block Header. The real
90          * uncompressed size of the data being compressed must match
91          * the Uncompressed Size or LZMA_HEADER_ERROR is returned.
92          *
93          * If Uncompressed Size is unknown, End of Payload Marker must
94          * be used. If uncompressed_size == LZMA_VLI_VALUE_UNKNOWN and
95          * has_eopm == 0, LZMA_HEADER_ERROR will be returned.
96          *
97          * Decoder: If this value is not LZMA_VLI_VALUE_UNKNOWN, it is
98          * compared to the real Uncompressed Size. If they do not match,
99          * LZMA_HEADER_ERROR is returned.
100          *
101          * Read by:
102          *  - lzma_block_header_size()
103          *  - lzma_block_header_encode()
104          *  - lzma_block_decoder()
105          *
106          * Written by:
107          *  - lzma_block_header_decode()
108          *  - lzma_block_encoder()
109          *  - lzma_block_decoder()
110          */
111         lzma_vli uncompressed_size;
112
113         /**
114          * \brief       Array of filters
115          *
116          * There can be 1-4 filters. The end of the array is marked with
117          * .id = LZMA_VLI_VALUE_UNKNOWN.
118          *
119          * Read by:
120          *  - lzma_block_header_size()
121          *  - lzma_block_header_encode()
122          *  - lzma_block_encoder()
123          *  - lzma_block_decoder()
124          *
125          * Written by:
126          *  - lzma_block_header_decode(): Note that this does NOT free()
127          *    the old filter options structures. All unused filters[] will
128          *    have .id == LZMA_VLI_VALUE_UNKNOWN and .options == NULL. If
129          *    decoding fails, all filters[] are guaranteed to be
130          *    LZMA_VLI_VALUE_UNKNOWN and NULL.
131          *
132          * \note        Because of the array is terminated with
133          *              .id = LZMA_VLI_VALUE_UNKNOWN, the actual array must
134          *              have LZMA_BLOCK_FILTERS_MAX + 1 members or the Block
135          *              Header decoder will overflow the buffer.
136          */
137         lzma_filter *filters;
138 #       define LZMA_BLOCK_FILTERS_MAX 4
139
140 } lzma_block;
141
142
143 /**
144  * \brief       Decodes the Block Header Size field
145  *
146  * To decode Block Header using lzma_block_header_decode(), the size of the
147  * Block Header has to be known and stored into lzma_block.header_size.
148  * The size can be calculated from the first byte of a Block using this macro.
149  * Note that if the first byte is 0x00, it indicates beginning of Index; use
150  * this macro only when the byte is not 0x00.
151  */
152 #define lzma_block_header_size_decode(b) (((uint32_t)(b) + 1) * 4)
153
154
155 /**
156  * \brief       Calculates the size of Block Header
157  *
158  * \return      - LZMA_OK: Size calculated successfully and stored to
159  *                options->header_size.
160  *              - LZMA_HEADER_ERROR: Unsupported filters or filter options.
161  *              - LZMA_PROG_ERROR: Invalid options
162  *
163  * \note        This doesn't check that all the options are valid i.e. this
164  *              may return LZMA_OK even if lzma_block_header_encode() or
165  *              lzma_block_encoder() would fail.
166  */
167 extern lzma_ret lzma_block_header_size(lzma_block *options)
168                 lzma_attr_warn_unused_result;
169
170
171 /**
172  * \brief       Encodes Block Header
173  *
174  * Encoding of the Block options is done with a single call instead of
175  * first initializing and then doing the actual work with lzma_code().
176  *
177  * \param       out         Beginning of the output buffer. This must be
178  *                          at least options->header_size bytes.
179  * \param       options     Block options to be encoded.
180  *
181  * \return      - LZMA_OK: Encoding was successful. options->header_size
182  *                bytes were written to output buffer.
183  *              - LZMA_HEADER_ERROR: Invalid or unsupported options.
184  *              - LZMA_PROG_ERROR
185  */
186 extern lzma_ret lzma_block_header_encode(
187                 const lzma_block *options, uint8_t *out)
188                 lzma_attr_warn_unused_result;
189
190
191 /**
192  * \brief       Decodes Block Header
193  *
194  * Decoding of the Block options is done with a single call instead of
195  * first initializing and then doing the actual work with lzma_code().
196  *
197  * \param       options     Destination for block options
198  * \param       allocator   lzma_allocator for custom allocator functions.
199  *                          Set to NULL to use malloc().
200  * \param       in          Beginning of the input buffer. This must be
201  *                          at least options->header_size bytes.
202  *
203  * \return      - LZMA_OK: Decoding was successful. options->header_size
204  *                bytes were written to output buffer.
205  *              - LZMA_HEADER_ERROR: Invalid or unsupported options.
206  *              - LZMA_PROG_ERROR
207  */
208 extern lzma_ret lzma_block_header_decode(lzma_block *options,
209                 lzma_allocator *allocator, const uint8_t *in)
210                 lzma_attr_warn_unused_result;
211
212
213 /**
214  * \brief       Sets Compressed Size according to Total Size
215  *
216  * Block Header stores Compressed Size, but Index has Total Size. If the
217  * application has already parsed the Index and is now decoding Blocks,
218  * it can calculate Compressed Size from Total Size. This function does
219  * exactly that with error checking, so application doesn't need to check,
220  * for example, if the value in Index is too small to contain even the
221  * Block Header. Note that you need to call this function after decoding
222  * the Block Header field.
223  *
224  * \return      - LZMA_OK: options->compressed_size was set successfully.
225  *              - LZMA_DATA_ERROR: total_size is too small compared to
226  *                options->header_size and lzma_check_sizes[options->check].
227  *              - LZMA_PROG_ERROR: Some values are invalid. For example,
228  *                total_size and options->header_size must be multiples
229  *                of four, total_size must be at least 12, and
230  *                options->header_size between 8 and 1024 inclusive.
231  */
232 extern lzma_ret lzma_block_total_size_set(
233                 lzma_block *options, lzma_vli total_size)
234                 lzma_attr_warn_unused_result;
235
236
237 /**
238  * \brief       Calculates Total Size
239  *
240  * This function can be useful after decoding a Block to get Total Size
241  * that is stored in Index.
242  *
243  * \return      Total Size on success, or zero on error.
244  */
245 extern lzma_vli lzma_block_total_size_get(const lzma_block *options)
246                 lzma_attr_pure;
247
248
249 /**
250  * \brief       Initializes .lzma Block encoder
251  *
252  * This function is required for multi-thread encoding. It may also be
253  * useful when implementing custom file formats.
254  *
255  * \return      - LZMA_OK: All good, continue with lzma_code().
256  *              - LZMA_MEM_ERROR
257  *              - LZMA_HEADER_ERROR
258  *              - LZMA_DATA_ERROR: Limits (total_limit and uncompressed_limit)
259  *                have been reached already.
260  *              - LZMA_UNSUPPORTED_CHECK: options->check specfies a Check
261  *                that is not supported by this buid of liblzma. Initializing
262  *                the encoder failed.
263  *              - LZMA_PROG_ERROR
264  *
265  * lzma_code() can return FIXME
266  */
267 extern lzma_ret lzma_block_encoder(lzma_stream *strm, lzma_block *options)
268                 lzma_attr_warn_unused_result;
269
270
271 /**
272  * \brief       Initializes decoder for .lzma Block
273  *
274  * \return      - LZMA_OK: All good, continue with lzma_code().
275  *              - LZMA_UNSUPPORTED_CHECK: Initialization was successful, but
276  *                the given Check type is not supported, thus Check will be
277  *                ignored.
278  *              - LZMA_PROG_ERROR
279  *              - LZMA_MEM_ERROR
280  */
281 extern lzma_ret lzma_block_decoder(lzma_stream *strm, lzma_block *options)
282                 lzma_attr_warn_unused_result;