XZ Utils 5.3.4alpha
Data Structures | Functions | Variables
filter_encoder.c File Reference

Filter ID mapping to filter-specific functions. More...

#include "filter_encoder.h"
#include "filter_common.h"
#include "lzma_encoder.h"
#include "lzma2_encoder.h"
#include "simple_encoder.h"
#include "delta_encoder.h"

Data Structures

struct  lzma_filter_encoder
 

Functions

static const lzma_filter_encoderencoder_find (lzma_vli id)
 
lzma_bool lzma_filter_encoder_is_supported (lzma_vli id)
 Test if the given Filter ID is supported for encoding. More...
 
lzma_ret lzma_filters_update (lzma_stream *strm, const lzma_filter *filters)
 Update the filter chain in the encoder. More...
 
lzma_ret lzma_raw_encoder_init (lzma_next_coder *next, const lzma_allocator *allocator, const lzma_filter *options)
 
lzma_ret lzma_raw_encoder (lzma_stream *strm, const lzma_filter *options)
 Initialize raw encoder. More...
 
uint64_t lzma_raw_encoder_memusage (const lzma_filter *filters)
 Calculate approximate memory requirements for raw encoder. More...
 
uint64_t lzma_mt_block_size (const lzma_filter *filters)
 
lzma_ret lzma_properties_size (uint32_t *size, const lzma_filter *filter)
 Get the size of the Filter Properties field. More...
 
lzma_ret lzma_properties_encode (const lzma_filter *filter, uint8_t *props)
 Encode the Filter Properties field. More...
 

Variables

static const lzma_filter_encoder encoders []
 

Detailed Description

Filter ID mapping to filter-specific functions.

Function Documentation

◆ lzma_filter_encoder_is_supported()

lzma_bool lzma_filter_encoder_is_supported ( lzma_vli  id) const

Test if the given Filter ID is supported for encoding.

Return true if the give Filter ID is supported for encoding by this liblzma build. Otherwise false is returned.

There is no way to list which filters are available in this particular liblzma version and build. It would be useless, because the application couldn't know what kind of options the filter would need.

◆ lzma_filters_update()

lzma_ret lzma_filters_update ( lzma_stream strm,
const lzma_filter filters 
)

Update the filter chain in the encoder.

This function is for advanced users only. This function has two slightly different purposes:

  • After LZMA_FULL_FLUSH when using Stream encoder: Set a new filter chain, which will be used starting from the next Block.
  • After LZMA_SYNC_FLUSH using Raw, Block, or Stream encoder: Change the filter-specific options in the middle of encoding. The actual filters in the chain (Filter IDs) cannot be changed. In the future, it might become possible to change the filter options without using LZMA_SYNC_FLUSH.

While rarely useful, this function may be called also when no data has been compressed yet. In that case, this function will behave as if LZMA_FULL_FLUSH (Stream encoder) or LZMA_SYNC_FLUSH (Raw or Block encoder) had been used right before calling this function.

Returns
- LZMA_OK
  • LZMA_MEM_ERROR
  • LZMA_MEMLIMIT_ERROR
  • LZMA_OPTIONS_ERROR
  • LZMA_PROG_ERROR

References filters, lzma_stream::internal, LZMA_PROG_ERROR, lzma_raw_encoder_memusage(), lzma_internal_s::next, strm, and lzma_next_coder_s::update.

◆ lzma_raw_encoder()

lzma_ret lzma_raw_encoder ( lzma_stream strm,
const lzma_filter filters 
)

Initialize raw encoder.

This function may be useful when implementing custom file formats.

Parameters
strmPointer to properly prepared lzma_stream
filtersArray of lzma_filter structures. The end of the array must be marked with .id = LZMA_VLI_UNKNOWN.

The ‘action’ with lzma_code() can be LZMA_RUN, LZMA_SYNC_FLUSH (if the filter chain supports it), or LZMA_FINISH.

Returns
- LZMA_OK
  • LZMA_MEM_ERROR
  • LZMA_OPTIONS_ERROR
  • LZMA_PROG_ERROR

References lzma_next_strm_init.

◆ lzma_raw_encoder_memusage()

uint64_t lzma_raw_encoder_memusage ( const lzma_filter filters)

Calculate approximate memory requirements for raw encoder.

This function can be used to calculate the memory requirements for Block and Stream encoders too because Block and Stream encoders don't need significantly more memory than raw encoder.

Parameters
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN.
Returns
Number of bytes of memory required for the given filter chain when encoding. If an error occurs, for example due to unsupported filter chain, UINT64_MAX is returned.

Referenced by lzma_filters_update().

◆ lzma_properties_size()

lzma_ret lzma_properties_size ( uint32_t *  size,
const lzma_filter filter 
)

Get the size of the Filter Properties field.

This function may be useful when implementing custom file formats using the raw encoder and decoder.

Parameters
sizePointer to uint32_t to hold the size of the properties
filterFilter ID and options (the size of the properties may vary depending on the options)
Returns
- LZMA_OK
  • LZMA_OPTIONS_ERROR
  • LZMA_PROG_ERROR
Note
This function validates the Filter ID, but does not necessarily validate the options. Thus, it is possible that this returns LZMA_OK while the following call to lzma_properties_encode() returns LZMA_OPTIONS_ERROR.

Referenced by lzma_filter_flags_encode(), and lzma_filter_flags_size().

◆ lzma_properties_encode()

lzma_ret lzma_properties_encode ( const lzma_filter filter,
uint8_t *  props 
)

Encode the Filter Properties field.

Parameters
filterFilter ID and options
propsBuffer to hold the encoded options. The size of buffer must have been already determined with lzma_properties_size().
Returns
- LZMA_OK
  • LZMA_OPTIONS_ERROR
  • LZMA_PROG_ERROR
Note
Even this function won't validate more options than actually necessary. Thus, it is possible that encoding the properties succeeds but using the same options to initialize the encoder will fail.
If lzma_properties_size() indicated that the size of the Filter Properties field is zero, calling lzma_properties_encode() is not required, but it won't do any harm either.

Referenced by lzma_filter_flags_encode().