aboutsummaryrefslogblamecommitdiff
path: root/src/liblzma/api/lzma/block.h
blob: 210c1d87babe0cb7f6bce963cc31be516b6e35d4 (plain) (tree)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
























































































































































































































































































































































































































                                                                              
/**
 * \file        lzma/block.h
 * \brief       .lzma Block 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 the Block Header encoder and decoder
 *
 * Different things use different parts of this structure. Some read
 * some members, other functions write, and some do both. Only the
 * members listed for reading need to be initialized when the specified
 * functions are called. The members marked for writing will be assigned
 * new values at some point either by calling the given function or by
 * later calls to lzma_code().
 */
typedef struct {
	/**
	 * \brief       Type of integrity Check
	 *
	 * The type of the integrity Check is not stored into the Block
	 * Header, thus its value must be provided also when decoding.
	 *
	 * Read by:
	 *  - lzma_block_encoder()
	 *  - lzma_block_decoder()
	 */
	lzma_check_type check;

	/**
	 * \brief       Precense of CRC32 of the Block Header
	 *
	 * Set this to true if CRC32 of the Block Header should be
	 * calculated and stored in the Block Header.
	 *
	 * There is no way to autodetect if CRC32 is present in the Block
	 * Header, thus this information must be provided also when decoding.
	 *
	 * Read by:
	 *  - lzma_block_header_size()
	 *  - lzma_block_header_encoder()
	 *  - lzma_block_header_decoder()
	 */
	lzma_bool has_crc32;

	/**
	 * \brief       Usage of End of Payload Marker
	 *
	 * If this is true, End of Payload Marker is used even if
	 * Uncompressed Size is known.
	 *
	 * Read by:
	 *  - lzma_block_header_encoder()
	 *  - lzma_block_encoder()
	 *  - lzma_block_decoder()
	 *
	 * Written by:
	 *  - lzma_block_header_decoder()
	 */
	lzma_bool has_eopm;

	/**
	 * \brief       True if the Block is a Metadata Block
	 *
	 * If this is true, the Metadata bit will be set in the Block Header.
	 * It is up to the application to store correctly formatted data
	 * into Metadata Block.
	 *
	 * Read by:
	 *  - lzma_block_header_encoder()
	 *
	 * Written by:
	 *  - lzma_block_header_decoder()
	 */
	lzma_bool is_metadata;

	/**
	 * \brief       True if Uncompressed Size is in Block Footer
	 *
	 * Read by:
	 *  - lzma_block_encoder()
	 *  - lzma_block_decoder()
	 */
	lzma_bool has_uncompressed_size_in_footer;

	/**
	 * \brief       True if Backward Size is in Block Footer
	 *
	 * Read by:
	 *  - lzma_block_encoder()
	 *  - lzma_block_decoder()
	 */
	lzma_bool has_backward_size;

	/**
	 * \brief       True if Block coder should take care of Padding
	 *
	 * In liblzma, Stream decoder sets this to true when decoding
	 * Header Metadata Block or Data Blocks from Multi-Block Stream,
	 * and to false when decoding Single-Block Stream or Footer
	 * Metadata Block from a Multi-Block Stream.
	 *
	 * Read by:
	 *  - lzma_block_encoder()
	 *  - lzma_block_decoder()
	 */
	lzma_bool handle_padding;

	/**
	 * \brief       Size of the Compressed Data in bytes
	 *
	 * Usually you don't know this value when encoding in streamed mode.
	 * In non-streamed mode you can reserve space for this field when
	 * encoding the Block Header the first time, and then re-encode the
	 * Block Header and copy it over the original one after the encoding
	 * of the Block has been finished.
	 *
	 * Read by:
	 *  - lzma_block_header_size()
	 *  - lzma_block_header_encoder()
	 *  - lzma_block_encoder()
	 *  - lzma_block_decoder()
	 *
	 * Written by:
	 *  - lzma_block_header_decoder()
	 *  - lzma_block_encoder()
	 *  - lzma_block_decoder()
	 */
	lzma_vli compressed_size;

	/**
	 * \brief       Uncompressed Size in bytes
	 *
	 * Encoder: If this value is not LZMA_VLI_VALUE_UNKNOWN, it is stored
	 * to the Uncompressed Size field in the Block Header. The real
	 * uncompressed size of the data being compressed must match
	 * the Uncompressed Size or LZMA_HEADER_ERROR is returned.
	 *
	 * If Uncompressed Size is unknown, End of Payload Marker must
	 * be used. If uncompressed_size == LZMA_VLI_VALUE_UNKNOWN and
	 * has_eopm == 0, LZMA_HEADER_ERROR will be returned.
	 *
	 * Decoder: If this value is not LZMA_VLI_VALUE_UNKNOWN, it is
	 * compared to the real Uncompressed Size. If they do not match,
	 * LZMA_HEADER_ERROR is returned.
	 *
	 * Read by:
	 *  - lzma_block_header_size()
	 *  - lzma_block_header_encoder()
	 *  - lzma_block_encoder()
	 *  - lzma_block_decoder()
	 *
	 * Written by:
	 *  - lzma_block_header_decoder()
	 *  - lzma_block_encoder()
	 *  - lzma_block_decoder()
	 */
	lzma_vli uncompressed_size;

	/**
	 * \brief       Number of bytes to reserve for Compressed Size
	 *
	 * This is useful if you want to be able to store the Compressed Size
	 * to the Block Header, but you don't know it when starting to encode.
	 * Setting this to non-zero value at maximum of LZMA_VLI_BYTES_MAX,
	 * the Block Header encoder will force the Compressed Size field to
	 * occupy specified number of bytes. You can later rewrite the Block
	 * Header to contain correct information by using otherwise identical
	 * lzma_options_block structure except the correct compressed_size.
	 *
	 * Read by:
	 *  - lzma_block_header_size()
	 *  - lzma_block_header_encoder()
	 *
	 * Written by:
	 *  - lzma_block_header_decoder()
	 */
	uint32_t compressed_reserve;

	/**
	 * \brief       Number of bytes to reserve for Uncompressed Size
	 *
	 * See the description of compressed_size above.
	 *
	 * Read by:
	 *  - lzma_block_header_size()
	 *  - lzma_block_header_encoder()
	 *
	 * Written by:
	 *  - lzma_block_header_decoder()
	 */
	uint32_t uncompressed_reserve;

	/**
	 * \brief       Total Size of the Block in bytes
	 *
	 * This is useful in the decoder, which can verify the Total Size
	 * if it is known from Index.
	 *
	 * Read by:
	 *  - lzma_block_encoder()
	 *  - lzma_block_decoder()
	 *
	 * Written by:
	 *  - lzma_block_encoder()
	 *  - lzma_block_decoder()
	 */
	lzma_vli total_size;

	/**
	 * \brief       Upper limit of Total Size
	 *
	 * Read by:
	 *  - lzma_block_encoder()
	 *  - lzma_block_decoder()
	 */
	lzma_vli total_limit;

	/**
	 * \brief       Upper limit of Uncompressed Size
	 *
	 * Read by:
	 *  - lzma_block_encoder()
	 *  - lzma_block_decoder()
	 */
	lzma_vli uncompressed_limit;

	/**
	 * \brief       Array of filters
	 *
	 * There can be at maximum of seven filters. The end of the array
	 * is marked with .id = LZMA_VLI_VALUE_UNKNOWN. Minimum number of
	 * filters is zero; in that case, an implicit Copy filter is used.
	 *
	 * Read by:
	 *  - lzma_block_header_size()
	 *  - lzma_block_header_encoder()
	 *  - lzma_block_encoder()
	 *  - lzma_block_decoder()
	 *
	 * Written by:
	 *  - lzma_block_header_decoder(): Note that this does NOT free()
	 *    the old filter options structures. If decoding fails, the
	 *    caller must take care of freeing the options structures
	 *    that may have been allocated and decoded before the error
	 *    occurred.
	 */
	lzma_options_filter filters[8];

	/**
	 * \brief       Size of the Padding field
	 *
	 * The Padding field exist to allow aligning the Compressed Data field
	 * optimally in the Block. See lzma_options_stream.alignment in
	 * stream.h for more information.
	 *
	 * If you want the Block Header encoder to automatically calculate
	 * optimal size for the Padding field by looking at the information
	 * in filters[], set this to LZMA_BLOCK_HEADER_PADDING_AUTO. In that
	 * case, you must also set the aligmnet variable to tell the the
	 * encoder the aligmnet of the beginning of the Block Header.
	 *
	 * The decoder never sets this to LZMA_BLOCK_HEADER_PADDING_AUTO.
	 *
	 * Read by:
	 *  - lzma_block_header_size()
	 *  - lzma_block_header_encoder(): Note that this doesn't
	 *    accept LZMA_BLOCK_HEADER_PADDING_AUTO.
	 *
	 * Written by (these never set padding to
	 * LZMA_BLOCK_HEADER_PADDING_AUTO):
	 *  - lzma_block_header_size()
	 *  - lzma_block_header_decoder()
	 */
	int32_t padding;
#	define LZMA_BLOCK_HEADER_PADDING_AUTO (-1)
#	define LZMA_BLOCK_HEADER_PADDING_MIN 0
#	define LZMA_BLOCK_HEADER_PADDING_MAX 31

	/**
	 * \brief       Alignment of the beginning of the Block Header
	 *
	 * This variable is read only if padding has been set to
	 * LZMA_BLOCK_HEADER_PADDING_AUTO.
	 *
	 * Read by:
	 *  - lzma_block_header_size()
	 *  - lzma_block_header_encoder()
	 */
	uint32_t alignment;

	/**
	 * \brief       Size of the Block Header
	 *
	 * Read by:
	 *  - lzma_block_encoder()
	 *  - lzma_block_decoder()
	 *
	 * Written by:
	 *  - lzma_block_header_size()
	 *  - lzma_block_header_decoder()
	 */
	uint32_t header_size;

} lzma_options_block;


/**
 * \brief       Calculates the size of Header Padding and Block Header
 *
 * \return      - LZMA_OK: Size calculated successfully and stored to
 *                options->header_size.
 *              - LZMA_HEADER_ERROR: Unsupported filters or filter options.
 *              - LZMA_PROG_ERROR: Invalid options
 *
 * \note        This doesn't check that all the options are valid i.e. this
 *              may return LZMA_OK even if lzma_block_header_encode() or
 *              lzma_block_encoder() would fail.
 */
extern lzma_ret lzma_block_header_size(lzma_options_block *options);


/**
 * \brief       Encodes Block Header
 *
 * Encoding of the Block options is done with a single call instead of
 * first initializing and then doing the actual work with lzma_code().
 *
 * \param       out         Beginning of the output buffer. This must be
 *                          at least options->header_size bytes.
 * \param       options     Block options to be encoded.
 *
 * \return      - LZMA_OK: Encoding was successful. options->header_size
 *                bytes were written to output buffer.
 *              - LZMA_HEADER_ERROR: Invalid or unsupported options.
 *              - LZMA_PROG_ERROR
 */
extern lzma_ret lzma_block_header_encode(
		uint8_t *out, const lzma_options_block *options);


/**
 * \brief       Initializes Block Header decoder
 *
 * Because the results of this decoder are placed into *options,
 * strm->next_in, strm->avail_in, and strm->total_in are not used.
 *
 * The only valid `action' with lzma_code() is LZMA_RUN.
 *
 * \return      - LZMA_OK: Encoding was successful. options->header_size
 *                bytes were written to output buffer.
 *              - LZMA_HEADER_ERROR: Invalid or unsupported options.
 *              - LZMA_PROG_ERROR
 */
extern lzma_ret lzma_block_header_decoder(
		lzma_stream *strm, lzma_options_block *options);


/**
 * \brief       Initializes .lzma Block encoder
 *
 * This function is required for multi-thread encoding. It may also be
 * useful when implementing custom file formats.
 *
 * \return      - LZMA_OK: All good, continue with lzma_code().
 *              - LZMA_MEM_ERROR
 *              - LZMA_HEADER_ERROR
 *              - LZMA_DATA_ERROR: Limits (total_limit and uncompressed_limit)
 *                have been reached already.
 *              - LZMA_UNSUPPORTED_CHECK: options->check specfies a Check
 *                that is not supported by this buid of liblzma. Initializing
 *                the encoder failed.
 *              - LZMA_PROG_ERROR
 *
 * lzma_code() can return FIXME
 */
extern lzma_ret lzma_block_encoder(
		lzma_stream *strm, lzma_options_block *options);


/**
 * \brief       Initializes decoder for .lzma Block
 *
 * \return      - LZMA_OK: All good, continue with lzma_code().
 *              - LZMA_UNSUPPORTED_CHECK: Initialization was successful, but
 *                the given Check type is not supported, thus Check will be
 *                ignored.
 *              - LZMA_PROG_ERROR
 *              - LZMA_MEM_ERROR
 */
extern lzma_ret lzma_block_decoder(
		lzma_stream *strm, lzma_options_block *options);