/tmp/buildd/xz-utils-5.0.0/src/liblzma/common/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.
lzma_ret	lzma_filters_update (lzma_stream *strm, const lzma_filter *filters)
	Update the filter chain in the encoder.
lzma_ret	lzma_raw_encoder_init (lzma_next_coder *next, lzma_allocator *allocator, const lzma_filter *options)
lzma_ret	lzma_raw_encoder (lzma_stream *strm, const lzma_filter *options)
	Initialize raw encoder.
uint64_t	lzma_raw_encoder_memusage (const lzma_filter *filters)
	Calculate approximate memory requirements for raw encoder.
lzma_vli	lzma_chunk_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.
lzma_ret	lzma_properties_encode (const lzma_filter *filter, uint8_t *props)
	Encode the Filter Properties field.
Variables
static const lzma_filter_encoder	encoders []

---

Detailed Description

Filter ID mapping to filter-specific functions.

---

Function Documentation

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_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 lzma_filter::id, LZMA_FILTERS_MAX, lzma_raw_encoder_memusage(), and LZMA_VLI_UNKNOWN.

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.

Referenced by coder_init().

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.

Referenced by lzma_easy_encoder_memusage(), and lzma_filters_update().

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.

References LZMA_OPTIONS_ERROR, LZMA_VLI_MAX, and lzma_filter_encoder::props_size_get.

Referenced by lzma_filter_flags_encode(), and lzma_filter_flags_size().

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.

References lzma_filter_encoder::props_encode.

Referenced by lzma_filter_flags_encode().