1*3b35e7eeSXin LI /* SPDX-License-Identifier: 0BSD */ 2*3b35e7eeSXin LI 381ad8388SMartin Matuska /** 481ad8388SMartin Matuska * \file lzma/block.h 581ad8388SMartin Matuska * \brief .xz Block handling 6c917796cSXin LI * \note Never include this file directly. Use <lzma.h> instead. 781ad8388SMartin Matuska */ 881ad8388SMartin Matuska 981ad8388SMartin Matuska /* 1081ad8388SMartin Matuska * Author: Lasse Collin 1181ad8388SMartin Matuska */ 1281ad8388SMartin Matuska 1381ad8388SMartin Matuska #ifndef LZMA_H_INTERNAL 1481ad8388SMartin Matuska # error Never include this file directly. Use <lzma.h> instead. 1581ad8388SMartin Matuska #endif 1681ad8388SMartin Matuska 1781ad8388SMartin Matuska 1881ad8388SMartin Matuska /** 1981ad8388SMartin Matuska * \brief Options for the Block and Block Header encoders and decoders 2081ad8388SMartin Matuska * 2181ad8388SMartin Matuska * Different Block handling functions use different parts of this structure. 2281ad8388SMartin Matuska * Some read some members, other functions write, and some do both. Only the 2381ad8388SMartin Matuska * members listed for reading need to be initialized when the specified 2481ad8388SMartin Matuska * functions are called. The members marked for writing will be assigned 2581ad8388SMartin Matuska * new values at some point either by calling the given function or by 2681ad8388SMartin Matuska * later calls to lzma_code(). 2781ad8388SMartin Matuska */ 2881ad8388SMartin Matuska typedef struct { 2981ad8388SMartin Matuska /** 3081ad8388SMartin Matuska * \brief Block format version 3181ad8388SMartin Matuska * 3253200025SRui Paulo * To prevent API and ABI breakages when new features are needed, 33c917796cSXin LI * a version number is used to indicate which members in this 3453200025SRui Paulo * structure are in use: 3553200025SRui Paulo * - liblzma >= 5.0.0: version = 0 is supported. 3653200025SRui Paulo * - liblzma >= 5.1.4beta: Support for version = 1 was added, 37c917796cSXin LI * which adds the ignore_check member. 3853200025SRui Paulo * 3953200025SRui Paulo * If version is greater than one, most Block related functions 4053200025SRui Paulo * will return LZMA_OPTIONS_ERROR (lzma_block_header_decode() works 4153200025SRui Paulo * with any version value). 4281ad8388SMartin Matuska * 4381ad8388SMartin Matuska * Read by: 44c917796cSXin LI * - lzma_block_header_size() 45c917796cSXin LI * - lzma_block_header_encode() 46c917796cSXin LI * - lzma_block_header_decode() 47c917796cSXin LI * - lzma_block_compressed_size() 48c917796cSXin LI * - lzma_block_unpadded_size() 49c917796cSXin LI * - lzma_block_total_size() 50c917796cSXin LI * - lzma_block_encoder() 51c917796cSXin LI * - lzma_block_decoder() 52c917796cSXin LI * - lzma_block_buffer_encode() 53c917796cSXin LI * - lzma_block_uncomp_encode() 54c917796cSXin LI * - lzma_block_buffer_decode() 5581ad8388SMartin Matuska * 5681ad8388SMartin Matuska * Written by: 5781ad8388SMartin Matuska * - lzma_block_header_decode() 5881ad8388SMartin Matuska */ 5981ad8388SMartin Matuska uint32_t version; 6081ad8388SMartin Matuska 6181ad8388SMartin Matuska /** 62c917796cSXin LI * \brief Size of the Block Header field in bytes 6381ad8388SMartin Matuska * 6481ad8388SMartin Matuska * This is always a multiple of four. 6581ad8388SMartin Matuska * 6681ad8388SMartin Matuska * Read by: 6781ad8388SMartin Matuska * - lzma_block_header_encode() 6881ad8388SMartin Matuska * - lzma_block_header_decode() 6981ad8388SMartin Matuska * - lzma_block_compressed_size() 7081ad8388SMartin Matuska * - lzma_block_unpadded_size() 7181ad8388SMartin Matuska * - lzma_block_total_size() 7281ad8388SMartin Matuska * - lzma_block_decoder() 7381ad8388SMartin Matuska * - lzma_block_buffer_decode() 7481ad8388SMartin Matuska * 7581ad8388SMartin Matuska * Written by: 7681ad8388SMartin Matuska * - lzma_block_header_size() 7781ad8388SMartin Matuska * - lzma_block_buffer_encode() 78c917796cSXin LI * - lzma_block_uncomp_encode() 7981ad8388SMartin Matuska */ 8081ad8388SMartin Matuska uint32_t header_size; 8181ad8388SMartin Matuska # define LZMA_BLOCK_HEADER_SIZE_MIN 8 8281ad8388SMartin Matuska # define LZMA_BLOCK_HEADER_SIZE_MAX 1024 8381ad8388SMartin Matuska 8481ad8388SMartin Matuska /** 8581ad8388SMartin Matuska * \brief Type of integrity Check 8681ad8388SMartin Matuska * 8781ad8388SMartin Matuska * The Check ID is not stored into the Block Header, thus its value 8881ad8388SMartin Matuska * must be provided also when decoding. 8981ad8388SMartin Matuska * 9081ad8388SMartin Matuska * Read by: 9181ad8388SMartin Matuska * - lzma_block_header_encode() 9281ad8388SMartin Matuska * - lzma_block_header_decode() 9381ad8388SMartin Matuska * - lzma_block_compressed_size() 9481ad8388SMartin Matuska * - lzma_block_unpadded_size() 9581ad8388SMartin Matuska * - lzma_block_total_size() 9681ad8388SMartin Matuska * - lzma_block_encoder() 9781ad8388SMartin Matuska * - lzma_block_decoder() 9881ad8388SMartin Matuska * - lzma_block_buffer_encode() 9981ad8388SMartin Matuska * - lzma_block_buffer_decode() 10081ad8388SMartin Matuska */ 10181ad8388SMartin Matuska lzma_check check; 10281ad8388SMartin Matuska 10381ad8388SMartin Matuska /** 10481ad8388SMartin Matuska * \brief Size of the Compressed Data in bytes 10581ad8388SMartin Matuska * 10681ad8388SMartin Matuska * Encoding: If this is not LZMA_VLI_UNKNOWN, Block Header encoder 10781ad8388SMartin Matuska * will store this value to the Block Header. Block encoder doesn't 10881ad8388SMartin Matuska * care about this value, but will set it once the encoding has been 10981ad8388SMartin Matuska * finished. 11081ad8388SMartin Matuska * 11181ad8388SMartin Matuska * Decoding: If this is not LZMA_VLI_UNKNOWN, Block decoder will 11281ad8388SMartin Matuska * verify that the size of the Compressed Data field matches 11381ad8388SMartin Matuska * compressed_size. 11481ad8388SMartin Matuska * 11581ad8388SMartin Matuska * Usually you don't know this value when encoding in streamed mode, 11681ad8388SMartin Matuska * and thus cannot write this field into the Block Header. 11781ad8388SMartin Matuska * 11881ad8388SMartin Matuska * In non-streamed mode you can reserve space for this field before 11981ad8388SMartin Matuska * encoding the actual Block. After encoding the data, finish the 12081ad8388SMartin Matuska * Block by encoding the Block Header. Steps in detail: 12181ad8388SMartin Matuska * 12281ad8388SMartin Matuska * - Set compressed_size to some big enough value. If you don't know 12381ad8388SMartin Matuska * better, use LZMA_VLI_MAX, but remember that bigger values take 12481ad8388SMartin Matuska * more space in Block Header. 12581ad8388SMartin Matuska * 12681ad8388SMartin Matuska * - Call lzma_block_header_size() to see how much space you need to 12781ad8388SMartin Matuska * reserve for the Block Header. 12881ad8388SMartin Matuska * 12981ad8388SMartin Matuska * - Encode the Block using lzma_block_encoder() and lzma_code(). 13081ad8388SMartin Matuska * It sets compressed_size to the correct value. 13181ad8388SMartin Matuska * 13281ad8388SMartin Matuska * - Use lzma_block_header_encode() to encode the Block Header. 13381ad8388SMartin Matuska * Because space was reserved in the first step, you don't need 13481ad8388SMartin Matuska * to call lzma_block_header_size() anymore, because due to 13581ad8388SMartin Matuska * reserving, header_size has to be big enough. If it is "too big", 13681ad8388SMartin Matuska * lzma_block_header_encode() will add enough Header Padding to 13781ad8388SMartin Matuska * make Block Header to match the size specified by header_size. 13881ad8388SMartin Matuska * 13981ad8388SMartin Matuska * Read by: 14081ad8388SMartin Matuska * - lzma_block_header_size() 14181ad8388SMartin Matuska * - lzma_block_header_encode() 14281ad8388SMartin Matuska * - lzma_block_compressed_size() 14381ad8388SMartin Matuska * - lzma_block_unpadded_size() 14481ad8388SMartin Matuska * - lzma_block_total_size() 14581ad8388SMartin Matuska * - lzma_block_decoder() 14681ad8388SMartin Matuska * - lzma_block_buffer_decode() 14781ad8388SMartin Matuska * 14881ad8388SMartin Matuska * Written by: 14981ad8388SMartin Matuska * - lzma_block_header_decode() 15081ad8388SMartin Matuska * - lzma_block_compressed_size() 15181ad8388SMartin Matuska * - lzma_block_encoder() 15281ad8388SMartin Matuska * - lzma_block_decoder() 15381ad8388SMartin Matuska * - lzma_block_buffer_encode() 154c917796cSXin LI * - lzma_block_uncomp_encode() 15581ad8388SMartin Matuska * - lzma_block_buffer_decode() 15681ad8388SMartin Matuska */ 15781ad8388SMartin Matuska lzma_vli compressed_size; 15881ad8388SMartin Matuska 15981ad8388SMartin Matuska /** 16081ad8388SMartin Matuska * \brief Uncompressed Size in bytes 16181ad8388SMartin Matuska * 16281ad8388SMartin Matuska * This is handled very similarly to compressed_size above. 16381ad8388SMartin Matuska * 16481ad8388SMartin Matuska * uncompressed_size is needed by fewer functions than 16581ad8388SMartin Matuska * compressed_size. This is because uncompressed_size isn't 16681ad8388SMartin Matuska * needed to validate that Block stays within proper limits. 16781ad8388SMartin Matuska * 16881ad8388SMartin Matuska * Read by: 16981ad8388SMartin Matuska * - lzma_block_header_size() 17081ad8388SMartin Matuska * - lzma_block_header_encode() 17181ad8388SMartin Matuska * - lzma_block_decoder() 17281ad8388SMartin Matuska * - lzma_block_buffer_decode() 17381ad8388SMartin Matuska * 17481ad8388SMartin Matuska * Written by: 17581ad8388SMartin Matuska * - lzma_block_header_decode() 17681ad8388SMartin Matuska * - lzma_block_encoder() 17781ad8388SMartin Matuska * - lzma_block_decoder() 17881ad8388SMartin Matuska * - lzma_block_buffer_encode() 179c917796cSXin LI * - lzma_block_uncomp_encode() 18081ad8388SMartin Matuska * - lzma_block_buffer_decode() 18181ad8388SMartin Matuska */ 18281ad8388SMartin Matuska lzma_vli uncompressed_size; 18381ad8388SMartin Matuska 18481ad8388SMartin Matuska /** 18581ad8388SMartin Matuska * \brief Array of filters 18681ad8388SMartin Matuska * 18781ad8388SMartin Matuska * There can be 1-4 filters. The end of the array is marked with 18881ad8388SMartin Matuska * .id = LZMA_VLI_UNKNOWN. 18981ad8388SMartin Matuska * 19081ad8388SMartin Matuska * Read by: 19181ad8388SMartin Matuska * - lzma_block_header_size() 19281ad8388SMartin Matuska * - lzma_block_header_encode() 19381ad8388SMartin Matuska * - lzma_block_encoder() 19481ad8388SMartin Matuska * - lzma_block_decoder() 19581ad8388SMartin Matuska * - lzma_block_buffer_encode() 19681ad8388SMartin Matuska * - lzma_block_buffer_decode() 19781ad8388SMartin Matuska * 19881ad8388SMartin Matuska * Written by: 19981ad8388SMartin Matuska * - lzma_block_header_decode(): Note that this does NOT free() 20081ad8388SMartin Matuska * the old filter options structures. All unused filters[] will 20181ad8388SMartin Matuska * have .id == LZMA_VLI_UNKNOWN and .options == NULL. If 20281ad8388SMartin Matuska * decoding fails, all filters[] are guaranteed to be 20381ad8388SMartin Matuska * LZMA_VLI_UNKNOWN and NULL. 20481ad8388SMartin Matuska * 20581ad8388SMartin Matuska * \note Because of the array is terminated with 20681ad8388SMartin Matuska * .id = LZMA_VLI_UNKNOWN, the actual array must 20781ad8388SMartin Matuska * have LZMA_FILTERS_MAX + 1 members or the Block 20881ad8388SMartin Matuska * Header decoder will overflow the buffer. 20981ad8388SMartin Matuska */ 21081ad8388SMartin Matuska lzma_filter *filters; 21181ad8388SMartin Matuska 21281ad8388SMartin Matuska /** 21381ad8388SMartin Matuska * \brief Raw value stored in the Check field 21481ad8388SMartin Matuska * 21581ad8388SMartin Matuska * After successful coding, the first lzma_check_size(check) bytes 21681ad8388SMartin Matuska * of this array contain the raw value stored in the Check field. 21781ad8388SMartin Matuska * 21881ad8388SMartin Matuska * Note that CRC32 and CRC64 are stored in little endian byte order. 21981ad8388SMartin Matuska * Take it into account if you display the Check values to the user. 22081ad8388SMartin Matuska * 22181ad8388SMartin Matuska * Written by: 22281ad8388SMartin Matuska * - lzma_block_encoder() 22381ad8388SMartin Matuska * - lzma_block_decoder() 22481ad8388SMartin Matuska * - lzma_block_buffer_encode() 225c917796cSXin LI * - lzma_block_uncomp_encode() 22681ad8388SMartin Matuska * - lzma_block_buffer_decode() 22781ad8388SMartin Matuska */ 22881ad8388SMartin Matuska uint8_t raw_check[LZMA_CHECK_SIZE_MAX]; 22981ad8388SMartin Matuska 23081ad8388SMartin Matuska /* 23181ad8388SMartin Matuska * Reserved space to allow possible future extensions without 23281ad8388SMartin Matuska * breaking the ABI. You should not touch these, because the names 23381ad8388SMartin Matuska * of these variables may change. These are and will never be used 23481ad8388SMartin Matuska * with the currently supported options, so it is safe to leave these 23581ad8388SMartin Matuska * uninitialized. 23681ad8388SMartin Matuska */ 237c917796cSXin LI 238c917796cSXin LI /** \private Reserved member. */ 23981ad8388SMartin Matuska void *reserved_ptr1; 240c917796cSXin LI 241c917796cSXin LI /** \private Reserved member. */ 24281ad8388SMartin Matuska void *reserved_ptr2; 243c917796cSXin LI 244c917796cSXin LI /** \private Reserved member. */ 24581ad8388SMartin Matuska void *reserved_ptr3; 246c917796cSXin LI 247c917796cSXin LI /** \private Reserved member. */ 24881ad8388SMartin Matuska uint32_t reserved_int1; 249c917796cSXin LI 250c917796cSXin LI /** \private Reserved member. */ 25181ad8388SMartin Matuska uint32_t reserved_int2; 252c917796cSXin LI 253c917796cSXin LI /** \private Reserved member. */ 25481ad8388SMartin Matuska lzma_vli reserved_int3; 255c917796cSXin LI 256c917796cSXin LI /** \private Reserved member. */ 25781ad8388SMartin Matuska lzma_vli reserved_int4; 258c917796cSXin LI 259c917796cSXin LI /** \private Reserved member. */ 26081ad8388SMartin Matuska lzma_vli reserved_int5; 261c917796cSXin LI 262c917796cSXin LI /** \private Reserved member. */ 26381ad8388SMartin Matuska lzma_vli reserved_int6; 264c917796cSXin LI 265c917796cSXin LI /** \private Reserved member. */ 26681ad8388SMartin Matuska lzma_vli reserved_int7; 267c917796cSXin LI 268c917796cSXin LI /** \private Reserved member. */ 26981ad8388SMartin Matuska lzma_vli reserved_int8; 270c917796cSXin LI 271c917796cSXin LI /** \private Reserved member. */ 27281ad8388SMartin Matuska lzma_reserved_enum reserved_enum1; 273c917796cSXin LI 274c917796cSXin LI /** \private Reserved member. */ 27581ad8388SMartin Matuska lzma_reserved_enum reserved_enum2; 276c917796cSXin LI 277c917796cSXin LI /** \private Reserved member. */ 27881ad8388SMartin Matuska lzma_reserved_enum reserved_enum3; 279c917796cSXin LI 280c917796cSXin LI /** \private Reserved member. */ 28181ad8388SMartin Matuska lzma_reserved_enum reserved_enum4; 28253200025SRui Paulo 28353200025SRui Paulo /** 28453200025SRui Paulo * \brief A flag to Block decoder to not verify the Check field 28553200025SRui Paulo * 286c917796cSXin LI * This member is supported by liblzma >= 5.1.4beta if .version >= 1. 28753200025SRui Paulo * 28853200025SRui Paulo * If this is set to true, the integrity check won't be calculated 28953200025SRui Paulo * and verified. Unless you know what you are doing, you should 29053200025SRui Paulo * leave this to false. (A reason to set this to true is when the 29153200025SRui Paulo * file integrity is verified externally anyway and you want to 29253200025SRui Paulo * speed up the decompression, which matters mostly when using 29353200025SRui Paulo * SHA-256 as the integrity check.) 29453200025SRui Paulo * 29553200025SRui Paulo * If .version >= 1, read by: 29653200025SRui Paulo * - lzma_block_decoder() 29753200025SRui Paulo * - lzma_block_buffer_decode() 29853200025SRui Paulo * 29953200025SRui Paulo * Written by (.version is ignored): 30053200025SRui Paulo * - lzma_block_header_decode() always sets this to false 30153200025SRui Paulo */ 30253200025SRui Paulo lzma_bool ignore_check; 30353200025SRui Paulo 304c917796cSXin LI /** \private Reserved member. */ 30581ad8388SMartin Matuska lzma_bool reserved_bool2; 306c917796cSXin LI 307c917796cSXin LI /** \private Reserved member. */ 30881ad8388SMartin Matuska lzma_bool reserved_bool3; 309c917796cSXin LI 310c917796cSXin LI /** \private Reserved member. */ 31181ad8388SMartin Matuska lzma_bool reserved_bool4; 312c917796cSXin LI 313c917796cSXin LI /** \private Reserved member. */ 31481ad8388SMartin Matuska lzma_bool reserved_bool5; 315c917796cSXin LI 316c917796cSXin LI /** \private Reserved member. */ 31781ad8388SMartin Matuska lzma_bool reserved_bool6; 318c917796cSXin LI 319c917796cSXin LI /** \private Reserved member. */ 32081ad8388SMartin Matuska lzma_bool reserved_bool7; 321c917796cSXin LI 322c917796cSXin LI /** \private Reserved member. */ 32381ad8388SMartin Matuska lzma_bool reserved_bool8; 32481ad8388SMartin Matuska 32581ad8388SMartin Matuska } lzma_block; 32681ad8388SMartin Matuska 32781ad8388SMartin Matuska 32881ad8388SMartin Matuska /** 32981ad8388SMartin Matuska * \brief Decode the Block Header Size field 33081ad8388SMartin Matuska * 33181ad8388SMartin Matuska * To decode Block Header using lzma_block_header_decode(), the size of the 33281ad8388SMartin Matuska * Block Header has to be known and stored into lzma_block.header_size. 33381ad8388SMartin Matuska * The size can be calculated from the first byte of a Block using this macro. 33481ad8388SMartin Matuska * Note that if the first byte is 0x00, it indicates beginning of Index; use 33581ad8388SMartin Matuska * this macro only when the byte is not 0x00. 33681ad8388SMartin Matuska * 337c917796cSXin LI * There is no encoding macro because lzma_block_header_size() and 338c917796cSXin LI * lzma_block_header_encode() should be used. 33981ad8388SMartin Matuska */ 34081ad8388SMartin Matuska #define lzma_block_header_size_decode(b) (((uint32_t)(b) + 1) * 4) 34181ad8388SMartin Matuska 34281ad8388SMartin Matuska 34381ad8388SMartin Matuska /** 34481ad8388SMartin Matuska * \brief Calculate Block Header Size 34581ad8388SMartin Matuska * 34681ad8388SMartin Matuska * Calculate the minimum size needed for the Block Header field using the 34781ad8388SMartin Matuska * settings specified in the lzma_block structure. Note that it is OK to 34881ad8388SMartin Matuska * increase the calculated header_size value as long as it is a multiple of 34981ad8388SMartin Matuska * four and doesn't exceed LZMA_BLOCK_HEADER_SIZE_MAX. Increasing header_size 35081ad8388SMartin Matuska * just means that lzma_block_header_encode() will add Header Padding. 35181ad8388SMartin Matuska * 35281ad8388SMartin Matuska * \note This doesn't check that all the options are valid i.e. this 35381ad8388SMartin Matuska * may return LZMA_OK even if lzma_block_header_encode() or 35481ad8388SMartin Matuska * lzma_block_encoder() would fail. If you want to validate the 35581ad8388SMartin Matuska * filter chain, consider using lzma_memlimit_encoder() which as 35681ad8388SMartin Matuska * a side-effect validates the filter chain. 357c917796cSXin LI * 358c917796cSXin LI * \param block Block options 359c917796cSXin LI * 360c917796cSXin LI * \return Possible lzma_ret values: 361c917796cSXin LI * - LZMA_OK: Size calculated successfully and stored to 362c917796cSXin LI * block->header_size. 363c917796cSXin LI * - LZMA_OPTIONS_ERROR: Unsupported version, filters or 364c917796cSXin LI * filter options. 365c917796cSXin LI * - LZMA_PROG_ERROR: Invalid values like compressed_size == 0. 36681ad8388SMartin Matuska */ 36781ad8388SMartin Matuska extern LZMA_API(lzma_ret) lzma_block_header_size(lzma_block *block) 36881ad8388SMartin Matuska lzma_nothrow lzma_attr_warn_unused_result; 36981ad8388SMartin Matuska 37081ad8388SMartin Matuska 37181ad8388SMartin Matuska /** 37281ad8388SMartin Matuska * \brief Encode Block Header 37381ad8388SMartin Matuska * 37481ad8388SMartin Matuska * The caller must have calculated the size of the Block Header already with 37581ad8388SMartin Matuska * lzma_block_header_size(). If a value larger than the one calculated by 37681ad8388SMartin Matuska * lzma_block_header_size() is used, the Block Header will be padded to the 37781ad8388SMartin Matuska * specified size. 37881ad8388SMartin Matuska * 37981ad8388SMartin Matuska * \param block Block options to be encoded. 380c917796cSXin LI * \param[out] out Beginning of the output buffer. This must be 381c917796cSXin LI * at least block->header_size bytes. 38281ad8388SMartin Matuska * 383c917796cSXin LI * \return Possible lzma_ret values: 384c917796cSXin LI * - LZMA_OK: Encoding was successful. block->header_size 38581ad8388SMartin Matuska * bytes were written to output buffer. 38681ad8388SMartin Matuska * - LZMA_OPTIONS_ERROR: Invalid or unsupported options. 38781ad8388SMartin Matuska * - LZMA_PROG_ERROR: Invalid arguments, for example 38881ad8388SMartin Matuska * block->header_size is invalid or block->filters is NULL. 38981ad8388SMartin Matuska */ 39081ad8388SMartin Matuska extern LZMA_API(lzma_ret) lzma_block_header_encode( 39181ad8388SMartin Matuska const lzma_block *block, uint8_t *out) 39281ad8388SMartin Matuska lzma_nothrow lzma_attr_warn_unused_result; 39381ad8388SMartin Matuska 39481ad8388SMartin Matuska 39581ad8388SMartin Matuska /** 39681ad8388SMartin Matuska * \brief Decode Block Header 39781ad8388SMartin Matuska * 39853200025SRui Paulo * block->version should (usually) be set to the highest value supported 39953200025SRui Paulo * by the application. If the application sets block->version to a value 40053200025SRui Paulo * higher than supported by the current liblzma version, this function will 40153200025SRui Paulo * downgrade block->version to the highest value supported by it. Thus one 40253200025SRui Paulo * should check the value of block->version after calling this function if 40353200025SRui Paulo * block->version was set to a non-zero value and the application doesn't 40453200025SRui Paulo * otherwise know that the liblzma version being used is new enough to 40553200025SRui Paulo * support the specified block->version. 40681ad8388SMartin Matuska * 40781ad8388SMartin Matuska * The size of the Block Header must have already been decoded with 40881ad8388SMartin Matuska * lzma_block_header_size_decode() macro and stored to block->header_size. 40981ad8388SMartin Matuska * 410e08aa052SXin LI * The integrity check type from Stream Header must have been stored 411e08aa052SXin LI * to block->check. 412e08aa052SXin LI * 413542aef48SMartin Matuska * block->filters must have been allocated, but they don't need to be 414542aef48SMartin Matuska * initialized (possible existing filter options are not freed). 41581ad8388SMartin Matuska * 416c917796cSXin LI * \param[out] block Destination for Block options 41781ad8388SMartin Matuska * \param allocator lzma_allocator for custom allocator functions. 41881ad8388SMartin Matuska * Set to NULL to use malloc() (and also free() 41981ad8388SMartin Matuska * if an error occurs). 42081ad8388SMartin Matuska * \param in Beginning of the input buffer. This must be 42181ad8388SMartin Matuska * at least block->header_size bytes. 42281ad8388SMartin Matuska * 423c917796cSXin LI * \return Possible lzma_ret values: 424c917796cSXin LI * - LZMA_OK: Decoding was successful. block->header_size 42581ad8388SMartin Matuska * bytes were read from the input buffer. 42681ad8388SMartin Matuska * - LZMA_OPTIONS_ERROR: The Block Header specifies some 42781ad8388SMartin Matuska * unsupported options such as unsupported filters. This can 42881ad8388SMartin Matuska * happen also if block->version was set to a too low value 42981ad8388SMartin Matuska * compared to what would be required to properly represent 43081ad8388SMartin Matuska * the information stored in the Block Header. 43181ad8388SMartin Matuska * - LZMA_DATA_ERROR: Block Header is corrupt, for example, 43281ad8388SMartin Matuska * the CRC32 doesn't match. 43381ad8388SMartin Matuska * - LZMA_PROG_ERROR: Invalid arguments, for example 43481ad8388SMartin Matuska * block->header_size is invalid or block->filters is NULL. 43581ad8388SMartin Matuska */ 43681ad8388SMartin Matuska extern LZMA_API(lzma_ret) lzma_block_header_decode(lzma_block *block, 43753200025SRui Paulo const lzma_allocator *allocator, const uint8_t *in) 43881ad8388SMartin Matuska lzma_nothrow lzma_attr_warn_unused_result; 43981ad8388SMartin Matuska 44081ad8388SMartin Matuska 44181ad8388SMartin Matuska /** 44281ad8388SMartin Matuska * \brief Validate and set Compressed Size according to Unpadded Size 44381ad8388SMartin Matuska * 44481ad8388SMartin Matuska * Block Header stores Compressed Size, but Index has Unpadded Size. If the 44581ad8388SMartin Matuska * application has already parsed the Index and is now decoding Blocks, 44681ad8388SMartin Matuska * it can calculate Compressed Size from Unpadded Size. This function does 44781ad8388SMartin Matuska * exactly that with error checking: 44881ad8388SMartin Matuska * 44981ad8388SMartin Matuska * - Compressed Size calculated from Unpadded Size must be positive integer, 45081ad8388SMartin Matuska * that is, Unpadded Size must be big enough that after Block Header and 45181ad8388SMartin Matuska * Check fields there's still at least one byte for Compressed Size. 45281ad8388SMartin Matuska * 45381ad8388SMartin Matuska * - If Compressed Size was present in Block Header, the new value 45481ad8388SMartin Matuska * calculated from Unpadded Size is compared against the value 45581ad8388SMartin Matuska * from Block Header. 45681ad8388SMartin Matuska * 45781ad8388SMartin Matuska * \note This function must be called _after_ decoding the Block Header 45881ad8388SMartin Matuska * field so that it can properly validate Compressed Size if it 45981ad8388SMartin Matuska * was present in Block Header. 46081ad8388SMartin Matuska * 461c917796cSXin LI * \param block Block options: block->header_size must 462c917796cSXin LI * already be set with lzma_block_header_size(). 463c917796cSXin LI * \param unpadded_size Unpadded Size from the Index field in bytes 464c917796cSXin LI * 465c917796cSXin LI * \return Possible lzma_ret values: 466c917796cSXin LI * - LZMA_OK: block->compressed_size was set successfully. 46781ad8388SMartin Matuska * - LZMA_DATA_ERROR: unpadded_size is too small compared to 46881ad8388SMartin Matuska * block->header_size and lzma_check_size(block->check). 46981ad8388SMartin Matuska * - LZMA_PROG_ERROR: Some values are invalid. For example, 47081ad8388SMartin Matuska * block->header_size must be a multiple of four and 47181ad8388SMartin Matuska * between 8 and 1024 inclusive. 47281ad8388SMartin Matuska */ 47381ad8388SMartin Matuska extern LZMA_API(lzma_ret) lzma_block_compressed_size( 47481ad8388SMartin Matuska lzma_block *block, lzma_vli unpadded_size) 47581ad8388SMartin Matuska lzma_nothrow lzma_attr_warn_unused_result; 47681ad8388SMartin Matuska 47781ad8388SMartin Matuska 47881ad8388SMartin Matuska /** 47981ad8388SMartin Matuska * \brief Calculate Unpadded Size 48081ad8388SMartin Matuska * 48181ad8388SMartin Matuska * The Index field stores Unpadded Size and Uncompressed Size. The latter 48281ad8388SMartin Matuska * can be taken directly from the lzma_block structure after coding a Block, 48381ad8388SMartin Matuska * but Unpadded Size needs to be calculated from Block Header Size, 48481ad8388SMartin Matuska * Compressed Size, and size of the Check field. This is where this function 48581ad8388SMartin Matuska * is needed. 48681ad8388SMartin Matuska * 487c917796cSXin LI * \param block Block options: block->header_size must already be 488c917796cSXin LI * set with lzma_block_header_size(). 489c917796cSXin LI * 49081ad8388SMartin Matuska * \return Unpadded Size on success, or zero on error. 49181ad8388SMartin Matuska */ 49281ad8388SMartin Matuska extern LZMA_API(lzma_vli) lzma_block_unpadded_size(const lzma_block *block) 49381ad8388SMartin Matuska lzma_nothrow lzma_attr_pure; 49481ad8388SMartin Matuska 49581ad8388SMartin Matuska 49681ad8388SMartin Matuska /** 49781ad8388SMartin Matuska * \brief Calculate the total encoded size of a Block 49881ad8388SMartin Matuska * 49981ad8388SMartin Matuska * This is equivalent to lzma_block_unpadded_size() except that the returned 50081ad8388SMartin Matuska * value includes the size of the Block Padding field. 50181ad8388SMartin Matuska * 502c917796cSXin LI * \param block Block options: block->header_size must already be 503c917796cSXin LI * set with lzma_block_header_size(). 504c917796cSXin LI * 50581ad8388SMartin Matuska * \return On success, total encoded size of the Block. On error, 50681ad8388SMartin Matuska * zero is returned. 50781ad8388SMartin Matuska */ 50881ad8388SMartin Matuska extern LZMA_API(lzma_vli) lzma_block_total_size(const lzma_block *block) 50981ad8388SMartin Matuska lzma_nothrow lzma_attr_pure; 51081ad8388SMartin Matuska 51181ad8388SMartin Matuska 51281ad8388SMartin Matuska /** 51381ad8388SMartin Matuska * \brief Initialize .xz Block encoder 51481ad8388SMartin Matuska * 51581ad8388SMartin Matuska * Valid actions for lzma_code() are LZMA_RUN, LZMA_SYNC_FLUSH (only if the 51681ad8388SMartin Matuska * filter chain supports it), and LZMA_FINISH. 51781ad8388SMartin Matuska * 518c917796cSXin LI * The Block encoder encodes the Block Data, Block Padding, and Check value. 519c917796cSXin LI * It does NOT encode the Block Header which can be encoded with 520c917796cSXin LI * lzma_block_header_encode(). 521c917796cSXin LI * 522c917796cSXin LI * \param strm Pointer to lzma_stream that is at least initialized 523c917796cSXin LI * with LZMA_STREAM_INIT. 524c917796cSXin LI * \param block Block options: block->version, block->check, 525c917796cSXin LI * and block->filters must have been initialized. 526c917796cSXin LI * 527c917796cSXin LI * \return Possible lzma_ret values: 528c917796cSXin LI * - LZMA_OK: All good, continue with lzma_code(). 52981ad8388SMartin Matuska * - LZMA_MEM_ERROR 53081ad8388SMartin Matuska * - LZMA_OPTIONS_ERROR 53181ad8388SMartin Matuska * - LZMA_UNSUPPORTED_CHECK: block->check specifies a Check ID 532a8675d92SXin LI * that is not supported by this build of liblzma. Initializing 53381ad8388SMartin Matuska * the encoder failed. 53481ad8388SMartin Matuska * - LZMA_PROG_ERROR 53581ad8388SMartin Matuska */ 53681ad8388SMartin Matuska extern LZMA_API(lzma_ret) lzma_block_encoder( 53781ad8388SMartin Matuska lzma_stream *strm, lzma_block *block) 53881ad8388SMartin Matuska lzma_nothrow lzma_attr_warn_unused_result; 53981ad8388SMartin Matuska 54081ad8388SMartin Matuska 54181ad8388SMartin Matuska /** 54281ad8388SMartin Matuska * \brief Initialize .xz Block decoder 54381ad8388SMartin Matuska * 54481ad8388SMartin Matuska * Valid actions for lzma_code() are LZMA_RUN and LZMA_FINISH. Using 54581ad8388SMartin Matuska * LZMA_FINISH is not required. It is supported only for convenience. 54681ad8388SMartin Matuska * 547c917796cSXin LI * The Block decoder decodes the Block Data, Block Padding, and Check value. 548c917796cSXin LI * It does NOT decode the Block Header which can be decoded with 549c917796cSXin LI * lzma_block_header_decode(). 550c917796cSXin LI * 551c917796cSXin LI * \param strm Pointer to lzma_stream that is at least initialized 552c917796cSXin LI * with LZMA_STREAM_INIT. 553c917796cSXin LI * \param block Block options 554c917796cSXin LI * 555c917796cSXin LI * \return Possible lzma_ret values: 556c917796cSXin LI * - LZMA_OK: All good, continue with lzma_code(). 55781ad8388SMartin Matuska * - LZMA_PROG_ERROR 55881ad8388SMartin Matuska * - LZMA_MEM_ERROR 55981ad8388SMartin Matuska */ 56081ad8388SMartin Matuska extern LZMA_API(lzma_ret) lzma_block_decoder( 56181ad8388SMartin Matuska lzma_stream *strm, lzma_block *block) 56281ad8388SMartin Matuska lzma_nothrow lzma_attr_warn_unused_result; 56381ad8388SMartin Matuska 56481ad8388SMartin Matuska 56581ad8388SMartin Matuska /** 56681ad8388SMartin Matuska * \brief Calculate maximum output size for single-call Block encoding 56781ad8388SMartin Matuska * 56881ad8388SMartin Matuska * This is equivalent to lzma_stream_buffer_bound() but for .xz Blocks. 56981ad8388SMartin Matuska * See the documentation of lzma_stream_buffer_bound(). 570c917796cSXin LI * 571c917796cSXin LI * \param uncompressed_size Size of the data to be encoded with the 572c917796cSXin LI * single-call Block encoder. 573c917796cSXin LI * 574c917796cSXin LI * \return Maximum output size in bytes for single-call Block encoding. 57581ad8388SMartin Matuska */ 57681ad8388SMartin Matuska extern LZMA_API(size_t) lzma_block_buffer_bound(size_t uncompressed_size) 57781ad8388SMartin Matuska lzma_nothrow; 57881ad8388SMartin Matuska 57981ad8388SMartin Matuska 58081ad8388SMartin Matuska /** 58181ad8388SMartin Matuska * \brief Single-call .xz Block encoder 58281ad8388SMartin Matuska * 58381ad8388SMartin Matuska * In contrast to the multi-call encoder initialized with 58481ad8388SMartin Matuska * lzma_block_encoder(), this function encodes also the Block Header. This 58581ad8388SMartin Matuska * is required to make it possible to write appropriate Block Header also 58681ad8388SMartin Matuska * in case the data isn't compressible, and different filter chain has to be 58781ad8388SMartin Matuska * used to encode the data in uncompressed form using uncompressed chunks 58881ad8388SMartin Matuska * of the LZMA2 filter. 58981ad8388SMartin Matuska * 59081ad8388SMartin Matuska * When the data isn't compressible, header_size, compressed_size, and 59181ad8388SMartin Matuska * uncompressed_size are set just like when the data was compressible, but 59281ad8388SMartin Matuska * it is possible that header_size is too small to hold the filter chain 59381ad8388SMartin Matuska * specified in block->filters, because that isn't necessarily the filter 59481ad8388SMartin Matuska * chain that was actually used to encode the data. lzma_block_unpadded_size() 59581ad8388SMartin Matuska * still works normally, because it doesn't read the filters array. 59681ad8388SMartin Matuska * 59781ad8388SMartin Matuska * \param block Block options: block->version, block->check, 59881ad8388SMartin Matuska * and block->filters must have been initialized. 59981ad8388SMartin Matuska * \param allocator lzma_allocator for custom allocator functions. 60081ad8388SMartin Matuska * Set to NULL to use malloc() and free(). 60181ad8388SMartin Matuska * \param in Beginning of the input buffer 60281ad8388SMartin Matuska * \param in_size Size of the input buffer 603c917796cSXin LI * \param[out] out Beginning of the output buffer 604c917796cSXin LI * \param[out] out_pos The next byte will be written to out[*out_pos]. 60581ad8388SMartin Matuska * *out_pos is updated only if encoding succeeds. 60681ad8388SMartin Matuska * \param out_size Size of the out buffer; the first byte into 60781ad8388SMartin Matuska * which no data is written to is out[out_size]. 60881ad8388SMartin Matuska * 609c917796cSXin LI * \return Possible lzma_ret values: 610c917796cSXin LI * - LZMA_OK: Encoding was successful. 61181ad8388SMartin Matuska * - LZMA_BUF_ERROR: Not enough output buffer space. 612e24134bcSMartin Matuska * - LZMA_UNSUPPORTED_CHECK 61381ad8388SMartin Matuska * - LZMA_OPTIONS_ERROR 61481ad8388SMartin Matuska * - LZMA_MEM_ERROR 61581ad8388SMartin Matuska * - LZMA_DATA_ERROR 61681ad8388SMartin Matuska * - LZMA_PROG_ERROR 61781ad8388SMartin Matuska */ 61881ad8388SMartin Matuska extern LZMA_API(lzma_ret) lzma_block_buffer_encode( 61953200025SRui Paulo lzma_block *block, const lzma_allocator *allocator, 62053200025SRui Paulo const uint8_t *in, size_t in_size, 62153200025SRui Paulo uint8_t *out, size_t *out_pos, size_t out_size) 62253200025SRui Paulo lzma_nothrow lzma_attr_warn_unused_result; 62353200025SRui Paulo 62453200025SRui Paulo 62553200025SRui Paulo /** 62653200025SRui Paulo * \brief Single-call uncompressed .xz Block encoder 62753200025SRui Paulo * 62853200025SRui Paulo * This is like lzma_block_buffer_encode() except this doesn't try to 62953200025SRui Paulo * compress the data and instead encodes the data using LZMA2 uncompressed 63053200025SRui Paulo * chunks. The required output buffer size can be determined with 63153200025SRui Paulo * lzma_block_buffer_bound(). 63253200025SRui Paulo * 63353200025SRui Paulo * Since the data won't be compressed, this function ignores block->filters. 63453200025SRui Paulo * This function doesn't take lzma_allocator because this function doesn't 63553200025SRui Paulo * allocate any memory from the heap. 636c917796cSXin LI * 637c917796cSXin LI * \param block Block options: block->version, block->check, 638c917796cSXin LI * and block->filters must have been initialized. 639c917796cSXin LI * \param in Beginning of the input buffer 640c917796cSXin LI * \param in_size Size of the input buffer 641c917796cSXin LI * \param[out] out Beginning of the output buffer 642c917796cSXin LI * \param[out] out_pos The next byte will be written to out[*out_pos]. 643c917796cSXin LI * *out_pos is updated only if encoding succeeds. 644c917796cSXin LI * \param out_size Size of the out buffer; the first byte into 645c917796cSXin LI * which no data is written to is out[out_size]. 646c917796cSXin LI * 647c917796cSXin LI * \return Possible lzma_ret values: 648c917796cSXin LI * - LZMA_OK: Encoding was successful. 649c917796cSXin LI * - LZMA_BUF_ERROR: Not enough output buffer space. 650c917796cSXin LI * - LZMA_UNSUPPORTED_CHECK 651c917796cSXin LI * - LZMA_OPTIONS_ERROR 652c917796cSXin LI * - LZMA_MEM_ERROR 653c917796cSXin LI * - LZMA_DATA_ERROR 654c917796cSXin LI * - LZMA_PROG_ERROR 65553200025SRui Paulo */ 65653200025SRui Paulo extern LZMA_API(lzma_ret) lzma_block_uncomp_encode(lzma_block *block, 65781ad8388SMartin Matuska const uint8_t *in, size_t in_size, 65881ad8388SMartin Matuska uint8_t *out, size_t *out_pos, size_t out_size) 65981ad8388SMartin Matuska lzma_nothrow lzma_attr_warn_unused_result; 66081ad8388SMartin Matuska 66181ad8388SMartin Matuska 66281ad8388SMartin Matuska /** 66381ad8388SMartin Matuska * \brief Single-call .xz Block decoder 66481ad8388SMartin Matuska * 66581ad8388SMartin Matuska * This is single-call equivalent of lzma_block_decoder(), and requires that 66681ad8388SMartin Matuska * the caller has already decoded Block Header and checked its memory usage. 66781ad8388SMartin Matuska * 668c917796cSXin LI * \param block Block options 66981ad8388SMartin Matuska * \param allocator lzma_allocator for custom allocator functions. 67081ad8388SMartin Matuska * Set to NULL to use malloc() and free(). 67181ad8388SMartin Matuska * \param in Beginning of the input buffer 67281ad8388SMartin Matuska * \param in_pos The next byte will be read from in[*in_pos]. 67381ad8388SMartin Matuska * *in_pos is updated only if decoding succeeds. 67481ad8388SMartin Matuska * \param in_size Size of the input buffer; the first byte that 67581ad8388SMartin Matuska * won't be read is in[in_size]. 676c917796cSXin LI * \param[out] out Beginning of the output buffer 677c917796cSXin LI * \param[out] out_pos The next byte will be written to out[*out_pos]. 67881ad8388SMartin Matuska * *out_pos is updated only if encoding succeeds. 67981ad8388SMartin Matuska * \param out_size Size of the out buffer; the first byte into 68081ad8388SMartin Matuska * which no data is written to is out[out_size]. 68181ad8388SMartin Matuska * 682c917796cSXin LI * \return Possible lzma_ret values: 683c917796cSXin LI * - LZMA_OK: Decoding was successful. 68481ad8388SMartin Matuska * - LZMA_OPTIONS_ERROR 68581ad8388SMartin Matuska * - LZMA_DATA_ERROR 68681ad8388SMartin Matuska * - LZMA_MEM_ERROR 68781ad8388SMartin Matuska * - LZMA_BUF_ERROR: Output buffer was too small. 68881ad8388SMartin Matuska * - LZMA_PROG_ERROR 68981ad8388SMartin Matuska */ 69081ad8388SMartin Matuska extern LZMA_API(lzma_ret) lzma_block_buffer_decode( 69153200025SRui Paulo lzma_block *block, const lzma_allocator *allocator, 69281ad8388SMartin Matuska const uint8_t *in, size_t *in_pos, size_t in_size, 69381ad8388SMartin Matuska uint8_t *out, size_t *out_pos, size_t out_size) 69481ad8388SMartin Matuska lzma_nothrow; 695