1 | /** |
2 | * \file lzma/block.h |
3 | * \brief .xz Block handling |
4 | */ |
5 | |
6 | /* |
7 | * Author: Lasse Collin |
8 | * |
9 | * This file has been put into the public domain. |
10 | * You can do whatever you want with this file. |
11 | * |
12 | * See ../lzma.h for information about liblzma as a whole. |
13 | */ |
14 | |
15 | #ifndef LZMA_H_INTERNAL |
16 | # error Never include this file directly. Use <lzma.h> instead. |
17 | #endif |
18 | |
19 | |
20 | /** |
21 | * \brief Options for the Block and Block Header encoders and decoders |
22 | * |
23 | * Different Block handling functions use different parts of this structure. |
24 | * Some read some members, other functions write, and some do both. Only the |
25 | * members listed for reading need to be initialized when the specified |
26 | * functions are called. The members marked for writing will be assigned |
27 | * new values at some point either by calling the given function or by |
28 | * later calls to lzma_code(). |
29 | */ |
30 | typedef struct { |
31 | /** |
32 | * \brief Block format version |
33 | * |
34 | * To prevent API and ABI breakages if new features are needed in |
35 | * the Block field, a version number is used to indicate which |
36 | * fields in this structure are in use. For now, version must always |
37 | * be zero. With non-zero version, most Block related functions will |
38 | * return LZMA_OPTIONS_ERROR. |
39 | * |
40 | * Read by: |
41 | * - All functions that take pointer to lzma_block as argument, |
42 | * including lzma_block_header_decode(). |
43 | * |
44 | * Written by: |
45 | * - lzma_block_header_decode() |
46 | */ |
47 | uint32_t version; |
48 | |
49 | /** |
50 | * \brief Size of the Block Header field |
51 | * |
52 | * This is always a multiple of four. |
53 | * |
54 | * Read by: |
55 | * - lzma_block_header_encode() |
56 | * - lzma_block_header_decode() |
57 | * - lzma_block_compressed_size() |
58 | * - lzma_block_unpadded_size() |
59 | * - lzma_block_total_size() |
60 | * - lzma_block_decoder() |
61 | * - lzma_block_buffer_decode() |
62 | * |
63 | * Written by: |
64 | * - lzma_block_header_size() |
65 | * - lzma_block_buffer_encode() |
66 | */ |
67 | uint32_t ; |
68 | # define LZMA_BLOCK_HEADER_SIZE_MIN 8 |
69 | # define LZMA_BLOCK_HEADER_SIZE_MAX 1024 |
70 | |
71 | /** |
72 | * \brief Type of integrity Check |
73 | * |
74 | * The Check ID is not stored into the Block Header, thus its value |
75 | * must be provided also when decoding. |
76 | * |
77 | * Read by: |
78 | * - lzma_block_header_encode() |
79 | * - lzma_block_header_decode() |
80 | * - lzma_block_compressed_size() |
81 | * - lzma_block_unpadded_size() |
82 | * - lzma_block_total_size() |
83 | * - lzma_block_encoder() |
84 | * - lzma_block_decoder() |
85 | * - lzma_block_buffer_encode() |
86 | * - lzma_block_buffer_decode() |
87 | */ |
88 | lzma_check check; |
89 | |
90 | /** |
91 | * \brief Size of the Compressed Data in bytes |
92 | * |
93 | * Encoding: If this is not LZMA_VLI_UNKNOWN, Block Header encoder |
94 | * will store this value to the Block Header. Block encoder doesn't |
95 | * care about this value, but will set it once the encoding has been |
96 | * finished. |
97 | * |
98 | * Decoding: If this is not LZMA_VLI_UNKNOWN, Block decoder will |
99 | * verify that the size of the Compressed Data field matches |
100 | * compressed_size. |
101 | * |
102 | * Usually you don't know this value when encoding in streamed mode, |
103 | * and thus cannot write this field into the Block Header. |
104 | * |
105 | * In non-streamed mode you can reserve space for this field before |
106 | * encoding the actual Block. After encoding the data, finish the |
107 | * Block by encoding the Block Header. Steps in detail: |
108 | * |
109 | * - Set compressed_size to some big enough value. If you don't know |
110 | * better, use LZMA_VLI_MAX, but remember that bigger values take |
111 | * more space in Block Header. |
112 | * |
113 | * - Call lzma_block_header_size() to see how much space you need to |
114 | * reserve for the Block Header. |
115 | * |
116 | * - Encode the Block using lzma_block_encoder() and lzma_code(). |
117 | * It sets compressed_size to the correct value. |
118 | * |
119 | * - Use lzma_block_header_encode() to encode the Block Header. |
120 | * Because space was reserved in the first step, you don't need |
121 | * to call lzma_block_header_size() anymore, because due to |
122 | * reserving, header_size has to be big enough. If it is "too big", |
123 | * lzma_block_header_encode() will add enough Header Padding to |
124 | * make Block Header to match the size specified by header_size. |
125 | * |
126 | * Read by: |
127 | * - lzma_block_header_size() |
128 | * - lzma_block_header_encode() |
129 | * - lzma_block_compressed_size() |
130 | * - lzma_block_unpadded_size() |
131 | * - lzma_block_total_size() |
132 | * - lzma_block_decoder() |
133 | * - lzma_block_buffer_decode() |
134 | * |
135 | * Written by: |
136 | * - lzma_block_header_decode() |
137 | * - lzma_block_compressed_size() |
138 | * - lzma_block_encoder() |
139 | * - lzma_block_decoder() |
140 | * - lzma_block_buffer_encode() |
141 | * - lzma_block_buffer_decode() |
142 | */ |
143 | lzma_vli compressed_size; |
144 | |
145 | /** |
146 | * \brief Uncompressed Size in bytes |
147 | * |
148 | * This is handled very similarly to compressed_size above. |
149 | * |
150 | * uncompressed_size is needed by fewer functions than |
151 | * compressed_size. This is because uncompressed_size isn't |
152 | * needed to validate that Block stays within proper limits. |
153 | * |
154 | * Read by: |
155 | * - lzma_block_header_size() |
156 | * - lzma_block_header_encode() |
157 | * - lzma_block_decoder() |
158 | * - lzma_block_buffer_decode() |
159 | * |
160 | * Written by: |
161 | * - lzma_block_header_decode() |
162 | * - lzma_block_encoder() |
163 | * - lzma_block_decoder() |
164 | * - lzma_block_buffer_encode() |
165 | * - lzma_block_buffer_decode() |
166 | */ |
167 | lzma_vli uncompressed_size; |
168 | |
169 | /** |
170 | * \brief Array of filters |
171 | * |
172 | * There can be 1-4 filters. The end of the array is marked with |
173 | * .id = LZMA_VLI_UNKNOWN. |
174 | * |
175 | * Read by: |
176 | * - lzma_block_header_size() |
177 | * - lzma_block_header_encode() |
178 | * - lzma_block_encoder() |
179 | * - lzma_block_decoder() |
180 | * - lzma_block_buffer_encode() |
181 | * - lzma_block_buffer_decode() |
182 | * |
183 | * Written by: |
184 | * - lzma_block_header_decode(): Note that this does NOT free() |
185 | * the old filter options structures. All unused filters[] will |
186 | * have .id == LZMA_VLI_UNKNOWN and .options == NULL. If |
187 | * decoding fails, all filters[] are guaranteed to be |
188 | * LZMA_VLI_UNKNOWN and NULL. |
189 | * |
190 | * \note Because of the array is terminated with |
191 | * .id = LZMA_VLI_UNKNOWN, the actual array must |
192 | * have LZMA_FILTERS_MAX + 1 members or the Block |
193 | * Header decoder will overflow the buffer. |
194 | */ |
195 | lzma_filter *filters; |
196 | |
197 | /** |
198 | * \brief Raw value stored in the Check field |
199 | * |
200 | * After successful coding, the first lzma_check_size(check) bytes |
201 | * of this array contain the raw value stored in the Check field. |
202 | * |
203 | * Note that CRC32 and CRC64 are stored in little endian byte order. |
204 | * Take it into account if you display the Check values to the user. |
205 | * |
206 | * Written by: |
207 | * - lzma_block_encoder() |
208 | * - lzma_block_decoder() |
209 | * - lzma_block_buffer_encode() |
210 | * - lzma_block_buffer_decode() |
211 | */ |
212 | uint8_t raw_check[LZMA_CHECK_SIZE_MAX]; |
213 | |
214 | /* |
215 | * Reserved space to allow possible future extensions without |
216 | * breaking the ABI. You should not touch these, because the names |
217 | * of these variables may change. These are and will never be used |
218 | * with the currently supported options, so it is safe to leave these |
219 | * uninitialized. |
220 | */ |
221 | void *reserved_ptr1; |
222 | void *reserved_ptr2; |
223 | void *reserved_ptr3; |
224 | uint32_t reserved_int1; |
225 | uint32_t reserved_int2; |
226 | lzma_vli reserved_int3; |
227 | lzma_vli reserved_int4; |
228 | lzma_vli reserved_int5; |
229 | lzma_vli reserved_int6; |
230 | lzma_vli reserved_int7; |
231 | lzma_vli reserved_int8; |
232 | lzma_reserved_enum reserved_enum1; |
233 | lzma_reserved_enum reserved_enum2; |
234 | lzma_reserved_enum reserved_enum3; |
235 | lzma_reserved_enum reserved_enum4; |
236 | lzma_bool reserved_bool1; |
237 | lzma_bool reserved_bool2; |
238 | lzma_bool reserved_bool3; |
239 | lzma_bool reserved_bool4; |
240 | lzma_bool reserved_bool5; |
241 | lzma_bool reserved_bool6; |
242 | lzma_bool reserved_bool7; |
243 | lzma_bool reserved_bool8; |
244 | |
245 | } lzma_block; |
246 | |
247 | |
248 | /** |
249 | * \brief Decode the Block Header Size field |
250 | * |
251 | * To decode Block Header using lzma_block_header_decode(), the size of the |
252 | * Block Header has to be known and stored into lzma_block.header_size. |
253 | * The size can be calculated from the first byte of a Block using this macro. |
254 | * Note that if the first byte is 0x00, it indicates beginning of Index; use |
255 | * this macro only when the byte is not 0x00. |
256 | * |
257 | * There is no encoding macro, because Block Header encoder is enough for that. |
258 | */ |
259 | #define lzma_block_header_size_decode(b) (((uint32_t)(b) + 1) * 4) |
260 | |
261 | |
262 | /** |
263 | * \brief Calculate Block Header Size |
264 | * |
265 | * Calculate the minimum size needed for the Block Header field using the |
266 | * settings specified in the lzma_block structure. Note that it is OK to |
267 | * increase the calculated header_size value as long as it is a multiple of |
268 | * four and doesn't exceed LZMA_BLOCK_HEADER_SIZE_MAX. Increasing header_size |
269 | * just means that lzma_block_header_encode() will add Header Padding. |
270 | * |
271 | * \return - LZMA_OK: Size calculated successfully and stored to |
272 | * block->header_size. |
273 | * - LZMA_OPTIONS_ERROR: Unsupported version, filters or |
274 | * filter options. |
275 | * - LZMA_PROG_ERROR: Invalid values like compressed_size == 0. |
276 | * |
277 | * \note This doesn't check that all the options are valid i.e. this |
278 | * may return LZMA_OK even if lzma_block_header_encode() or |
279 | * lzma_block_encoder() would fail. If you want to validate the |
280 | * filter chain, consider using lzma_memlimit_encoder() which as |
281 | * a side-effect validates the filter chain. |
282 | */ |
283 | extern LZMA_API(lzma_ret) (lzma_block *block) |
284 | lzma_nothrow lzma_attr_warn_unused_result; |
285 | |
286 | |
287 | /** |
288 | * \brief Encode Block Header |
289 | * |
290 | * The caller must have calculated the size of the Block Header already with |
291 | * lzma_block_header_size(). If a value larger than the one calculated by |
292 | * lzma_block_header_size() is used, the Block Header will be padded to the |
293 | * specified size. |
294 | * |
295 | * \param out Beginning of the output buffer. This must be |
296 | * at least block->header_size bytes. |
297 | * \param block Block options to be encoded. |
298 | * |
299 | * \return - LZMA_OK: Encoding was successful. block->header_size |
300 | * bytes were written to output buffer. |
301 | * - LZMA_OPTIONS_ERROR: Invalid or unsupported options. |
302 | * - LZMA_PROG_ERROR: Invalid arguments, for example |
303 | * block->header_size is invalid or block->filters is NULL. |
304 | */ |
305 | extern LZMA_API(lzma_ret) ( |
306 | const lzma_block *block, uint8_t *out) |
307 | lzma_nothrow lzma_attr_warn_unused_result; |
308 | |
309 | |
310 | /** |
311 | * \brief Decode Block Header |
312 | * |
313 | * block->version should be set to the highest value supported by the |
314 | * application; currently the only possible version is zero. This function |
315 | * will set version to the lowest value that still supports all the features |
316 | * required by the Block Header. |
317 | * |
318 | * The size of the Block Header must have already been decoded with |
319 | * lzma_block_header_size_decode() macro and stored to block->header_size. |
320 | * |
321 | * block->filters must have been allocated, but they don't need to be |
322 | * initialized (possible existing filter options are not freed). |
323 | * |
324 | * \param block Destination for Block options. |
325 | * \param allocator lzma_allocator for custom allocator functions. |
326 | * Set to NULL to use malloc() (and also free() |
327 | * if an error occurs). |
328 | * \param in Beginning of the input buffer. This must be |
329 | * at least block->header_size bytes. |
330 | * |
331 | * \return - LZMA_OK: Decoding was successful. block->header_size |
332 | * bytes were read from the input buffer. |
333 | * - LZMA_OPTIONS_ERROR: The Block Header specifies some |
334 | * unsupported options such as unsupported filters. This can |
335 | * happen also if block->version was set to a too low value |
336 | * compared to what would be required to properly represent |
337 | * the information stored in the Block Header. |
338 | * - LZMA_DATA_ERROR: Block Header is corrupt, for example, |
339 | * the CRC32 doesn't match. |
340 | * - LZMA_PROG_ERROR: Invalid arguments, for example |
341 | * block->header_size is invalid or block->filters is NULL. |
342 | */ |
343 | extern LZMA_API(lzma_ret) (lzma_block *block, |
344 | lzma_allocator *allocator, const uint8_t *in) |
345 | lzma_nothrow lzma_attr_warn_unused_result; |
346 | |
347 | |
348 | /** |
349 | * \brief Validate and set Compressed Size according to Unpadded Size |
350 | * |
351 | * Block Header stores Compressed Size, but Index has Unpadded Size. If the |
352 | * application has already parsed the Index and is now decoding Blocks, |
353 | * it can calculate Compressed Size from Unpadded Size. This function does |
354 | * exactly that with error checking: |
355 | * |
356 | * - Compressed Size calculated from Unpadded Size must be positive integer, |
357 | * that is, Unpadded Size must be big enough that after Block Header and |
358 | * Check fields there's still at least one byte for Compressed Size. |
359 | * |
360 | * - If Compressed Size was present in Block Header, the new value |
361 | * calculated from Unpadded Size is compared against the value |
362 | * from Block Header. |
363 | * |
364 | * \note This function must be called _after_ decoding the Block Header |
365 | * field so that it can properly validate Compressed Size if it |
366 | * was present in Block Header. |
367 | * |
368 | * \return - LZMA_OK: block->compressed_size was set successfully. |
369 | * - LZMA_DATA_ERROR: unpadded_size is too small compared to |
370 | * block->header_size and lzma_check_size(block->check). |
371 | * - LZMA_PROG_ERROR: Some values are invalid. For example, |
372 | * block->header_size must be a multiple of four and |
373 | * between 8 and 1024 inclusive. |
374 | */ |
375 | extern LZMA_API(lzma_ret) lzma_block_compressed_size( |
376 | lzma_block *block, lzma_vli unpadded_size) |
377 | lzma_nothrow lzma_attr_warn_unused_result; |
378 | |
379 | |
380 | /** |
381 | * \brief Calculate Unpadded Size |
382 | * |
383 | * The Index field stores Unpadded Size and Uncompressed Size. The latter |
384 | * can be taken directly from the lzma_block structure after coding a Block, |
385 | * but Unpadded Size needs to be calculated from Block Header Size, |
386 | * Compressed Size, and size of the Check field. This is where this function |
387 | * is needed. |
388 | * |
389 | * \return Unpadded Size on success, or zero on error. |
390 | */ |
391 | extern LZMA_API(lzma_vli) lzma_block_unpadded_size(const lzma_block *block) |
392 | lzma_nothrow lzma_attr_pure; |
393 | |
394 | |
395 | /** |
396 | * \brief Calculate the total encoded size of a Block |
397 | * |
398 | * This is equivalent to lzma_block_unpadded_size() except that the returned |
399 | * value includes the size of the Block Padding field. |
400 | * |
401 | * \return On success, total encoded size of the Block. On error, |
402 | * zero is returned. |
403 | */ |
404 | extern LZMA_API(lzma_vli) lzma_block_total_size(const lzma_block *block) |
405 | lzma_nothrow lzma_attr_pure; |
406 | |
407 | |
408 | /** |
409 | * \brief Initialize .xz Block encoder |
410 | * |
411 | * Valid actions for lzma_code() are LZMA_RUN, LZMA_SYNC_FLUSH (only if the |
412 | * filter chain supports it), and LZMA_FINISH. |
413 | * |
414 | * \return - LZMA_OK: All good, continue with lzma_code(). |
415 | * - LZMA_MEM_ERROR |
416 | * - LZMA_OPTIONS_ERROR |
417 | * - LZMA_UNSUPPORTED_CHECK: block->check specifies a Check ID |
418 | * that is not supported by this buid of liblzma. Initializing |
419 | * the encoder failed. |
420 | * - LZMA_PROG_ERROR |
421 | */ |
422 | extern LZMA_API(lzma_ret) lzma_block_encoder( |
423 | lzma_stream *strm, lzma_block *block) |
424 | lzma_nothrow lzma_attr_warn_unused_result; |
425 | |
426 | |
427 | /** |
428 | * \brief Initialize .xz Block decoder |
429 | * |
430 | * Valid actions for lzma_code() are LZMA_RUN and LZMA_FINISH. Using |
431 | * LZMA_FINISH is not required. It is supported only for convenience. |
432 | * |
433 | * \return - LZMA_OK: All good, continue with lzma_code(). |
434 | * - LZMA_UNSUPPORTED_CHECK: Initialization was successful, but |
435 | * the given Check ID is not supported, thus Check will be |
436 | * ignored. |
437 | * - LZMA_PROG_ERROR |
438 | * - LZMA_MEM_ERROR |
439 | */ |
440 | extern LZMA_API(lzma_ret) lzma_block_decoder( |
441 | lzma_stream *strm, lzma_block *block) |
442 | lzma_nothrow lzma_attr_warn_unused_result; |
443 | |
444 | |
445 | /** |
446 | * \brief Calculate maximum output size for single-call Block encoding |
447 | * |
448 | * This is equivalent to lzma_stream_buffer_bound() but for .xz Blocks. |
449 | * See the documentation of lzma_stream_buffer_bound(). |
450 | */ |
451 | extern LZMA_API(size_t) lzma_block_buffer_bound(size_t uncompressed_size) |
452 | lzma_nothrow; |
453 | |
454 | |
455 | /** |
456 | * \brief Single-call .xz Block encoder |
457 | * |
458 | * In contrast to the multi-call encoder initialized with |
459 | * lzma_block_encoder(), this function encodes also the Block Header. This |
460 | * is required to make it possible to write appropriate Block Header also |
461 | * in case the data isn't compressible, and different filter chain has to be |
462 | * used to encode the data in uncompressed form using uncompressed chunks |
463 | * of the LZMA2 filter. |
464 | * |
465 | * When the data isn't compressible, header_size, compressed_size, and |
466 | * uncompressed_size are set just like when the data was compressible, but |
467 | * it is possible that header_size is too small to hold the filter chain |
468 | * specified in block->filters, because that isn't necessarily the filter |
469 | * chain that was actually used to encode the data. lzma_block_unpadded_size() |
470 | * still works normally, because it doesn't read the filters array. |
471 | * |
472 | * \param block Block options: block->version, block->check, |
473 | * and block->filters must have been initialized. |
474 | * \param allocator lzma_allocator for custom allocator functions. |
475 | * Set to NULL to use malloc() and free(). |
476 | * \param in Beginning of the input buffer |
477 | * \param in_size Size of the input buffer |
478 | * \param out Beginning of the output buffer |
479 | * \param out_pos The next byte will be written to out[*out_pos]. |
480 | * *out_pos is updated only if encoding succeeds. |
481 | * \param out_size Size of the out buffer; the first byte into |
482 | * which no data is written to is out[out_size]. |
483 | * |
484 | * \return - LZMA_OK: Encoding was successful. |
485 | * - LZMA_BUF_ERROR: Not enough output buffer space. |
486 | * - LZMA_UNSUPPORTED_CHECK |
487 | * - LZMA_OPTIONS_ERROR |
488 | * - LZMA_MEM_ERROR |
489 | * - LZMA_DATA_ERROR |
490 | * - LZMA_PROG_ERROR |
491 | */ |
492 | extern LZMA_API(lzma_ret) lzma_block_buffer_encode( |
493 | lzma_block *block, lzma_allocator *allocator, |
494 | const uint8_t *in, size_t in_size, |
495 | uint8_t *out, size_t *out_pos, size_t out_size) |
496 | lzma_nothrow lzma_attr_warn_unused_result; |
497 | |
498 | |
499 | /** |
500 | * \brief Single-call .xz Block decoder |
501 | * |
502 | * This is single-call equivalent of lzma_block_decoder(), and requires that |
503 | * the caller has already decoded Block Header and checked its memory usage. |
504 | * |
505 | * \param block Block options just like with lzma_block_decoder(). |
506 | * \param allocator lzma_allocator for custom allocator functions. |
507 | * Set to NULL to use malloc() and free(). |
508 | * \param in Beginning of the input buffer |
509 | * \param in_pos The next byte will be read from in[*in_pos]. |
510 | * *in_pos is updated only if decoding succeeds. |
511 | * \param in_size Size of the input buffer; the first byte that |
512 | * won't be read is in[in_size]. |
513 | * \param out Beginning of the output buffer |
514 | * \param out_pos The next byte will be written to out[*out_pos]. |
515 | * *out_pos is updated only if encoding succeeds. |
516 | * \param out_size Size of the out buffer; the first byte into |
517 | * which no data is written to is out[out_size]. |
518 | * |
519 | * \return - LZMA_OK: Decoding was successful. |
520 | * - LZMA_OPTIONS_ERROR |
521 | * - LZMA_DATA_ERROR |
522 | * - LZMA_MEM_ERROR |
523 | * - LZMA_BUF_ERROR: Output buffer was too small. |
524 | * - LZMA_PROG_ERROR |
525 | */ |
526 | extern LZMA_API(lzma_ret) lzma_block_buffer_decode( |
527 | lzma_block *block, lzma_allocator *allocator, |
528 | const uint8_t *in, size_t *in_pos, size_t in_size, |
529 | uint8_t *out, size_t *out_pos, size_t out_size) |
530 | lzma_nothrow; |
531 | |