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_encoder * | encoder_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

  strm | Pointer to properly prepared lzma_stream
  filters | Array 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

  filters | Array 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

  size | Pointer to uint32_t to hold the size of the properties
  filter | Filter 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

  filter | Filter ID and options
  props | Buffer 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().