lzma_block Struct Reference

Options for the Block and Block Header encoders and decoders. More...

#include <block.h>

Data Fields

uint32_t version
 Block format version.
uint32_t header_size
 Size of the Block Header field.
lzma_check check
 Type of integrity Check.
lzma_vli compressed_size
 Size of the Compressed Data in bytes.
lzma_vli uncompressed_size
 Uncompressed Size in bytes.
lzma_filterfilters
 Array of filters.
void * reserved_ptr1
void * reserved_ptr2
void * reserved_ptr3
uint32_t reserved_int1
uint32_t reserved_int2
lzma_vli reserved_int3
lzma_vli reserved_int4
lzma_vli reserved_int5
lzma_vli reserved_int6
lzma_vli reserved_int7
lzma_vli reserved_int8
lzma_reserved_enum reserved_enum1
lzma_reserved_enum reserved_enum2
lzma_reserved_enum reserved_enum3
lzma_reserved_enum reserved_enum4
lzma_bool reserved_bool1
lzma_bool reserved_bool2
lzma_bool reserved_bool3
lzma_bool reserved_bool4
lzma_bool reserved_bool5
lzma_bool reserved_bool6
lzma_bool reserved_bool7
lzma_bool reserved_bool8

Detailed Description

Options for the Block and Block Header encoders and decoders.

Different Block handling functions 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().


Field Documentation

Block format version.

To prevent API and ABI breakages if new features are needed in Block, a version number is used to indicate which fields in this structure are in use. For now, version must always be zero. With non-zero version, most Block related functions will return LZMA_OPTIONS_ERROR.

The decoding functions will always set this to the lowest value that supports all the features indicated by the Block Header field. The application must check that the version number set by the decoding functions is supported by the application. Otherwise it is possible that the application will decode the Block incorrectly.

Read by:

  • lzma_block_header_size()
  • lzma_block_header_encode()
  • lzma_block_compressed_size()
  • lzma_block_unpadded_size()
  • lzma_block_total_size()
  • lzma_block_encoder()
  • lzma_block_decoder()
  • lzma_block_buffer_encode()
  • lzma_block_buffer_decode()

Written by:

  • lzma_block_header_decode()

Size of the Block Header field.

This is always a multiple of four.

Read by:

  • lzma_block_header_encode()
  • lzma_block_header_decode()
  • lzma_block_compressed_size()
  • lzma_block_unpadded_size()
  • lzma_block_total_size()
  • lzma_block_decoder()
  • lzma_block_buffer_decode()

Written by:

  • lzma_block_header_size()
  • lzma_block_buffer_encode()

Type of integrity Check.

The Check ID is not stored into the Block Header, thus its value must be provided also when decoding.

Read by:

  • lzma_block_header_encode()
  • lzma_block_header_decode()
  • lzma_block_compressed_size()
  • lzma_block_unpadded_size()
  • lzma_block_total_size()
  • lzma_block_encoder()
  • lzma_block_decoder()
  • lzma_block_buffer_encode()
  • lzma_block_buffer_decode()

Size of the Compressed Data in bytes.

Encoding: If this is not LZMA_VLI_UNKNOWN, Block Header encoder will store this value to the Block Header. Block encoder doesn't care about this value, but will set it once the encoding has been finished.

Decoding: If this is not LZMA_VLI_UNKNOWN, Block decoder will verify that the size of the Compressed Data field matches compressed_size.

Usually you don't know this value when encoding in streamed mode, and thus cannot write this field into the Block Header.

In non-streamed mode you can reserve space for this field before encoding the actual Block. After encoding the data, finish the Block by encoding the Block Header. Steps in detail:

  • Set compressed_size to some big enough value. If you don't know better, use LZMA_VLI_MAX, but remember that bigger values take more space in Block Header.
  • Call lzma_block_header_size() to see how much space you need to reserve for the Block Header.
  • Encode the Block using lzma_block_encoder() and lzma_code(). It sets compressed_size to the correct value.
  • Use lzma_block_header_encode() to encode the Block Header. Because space was reserved in the first step, you don't need to call lzma_block_header_size() anymore, because due to reserving, header_size has to be big enough. If it is "too big", lzma_block_header_encode() will add enough Header Padding to make Block Header to match the size specified by header_size.

Read by:

  • lzma_block_header_size()
  • lzma_block_header_encode()
  • lzma_block_compressed_size()
  • lzma_block_unpadded_size()
  • lzma_block_total_size()
  • lzma_block_decoder()
  • lzma_block_buffer_decode()

Written by:

  • lzma_block_header_decode()
  • lzma_block_compressed_size()
  • lzma_block_encoder()
  • lzma_block_decoder()
  • lzma_block_buffer_encode()
  • lzma_block_buffer_decode()

Uncompressed Size in bytes.

This is handled very similarly to compressed_size above.

Unlike compressed_size, uncompressed_size is needed by fewer functions. This is because uncompressed_size isn't needed to validate that Block stays within proper limits.

Read by:

  • lzma_block_header_size()
  • lzma_block_header_encode()
  • lzma_block_decoder()
  • lzma_block_buffer_decode()

Written by:

  • lzma_block_header_decode()
  • lzma_block_encoder()
  • lzma_block_decoder()
  • lzma_block_buffer_encode()
  • lzma_block_buffer_decode()

Array of filters.

There can be 1-4 filters. The end of the array is marked with .id = LZMA_VLI_UNKNOWN.

Read by:

  • lzma_block_header_size()
  • lzma_block_header_encode()
  • lzma_block_encoder()
  • lzma_block_decoder()
  • lzma_block_buffer_encode()
  • lzma_block_buffer_decode()

Written by:

  • lzma_block_header_decode(): Note that this does NOT free() the old filter options structures. All unused filters[] will have .id == LZMA_VLI_UNKNOWN and .options == NULL. If decoding fails, all filters[] are guaranteed to be LZMA_VLI_UNKNOWN and NULL.
Note:
Because of the array is terminated with .id = LZMA_VLI_UNKNOWN, the actual array must have LZMA_FILTERS_MAX + 1 members or the Block Header decoder will overflow the buffer.

The documentation for this struct was generated from the following file:

Generated on Tue Oct 6 14:02:23 2009 for XZ Utils by  doxygen 1.6.1