src/liblzma/api/lzma/filter.h File Reference

Common filter related types. More...

Data Structures

struct  lzma_filter
 Filter options. More...

Defines

#define LZMA_FILTERS_MAX   4
 Maximum number of filters in a chain.

Functions

 LZMA_API (lzma_bool) lzma_filter_encoder_is_supported(lzma_vli id)
 Test if the given Filter ID is supported for encoding.
 LZMA_API (uint64_t) lzma_raw_encoder_memusage(const lzma_filter *filters) lzma_attr_pure
 Calculate rough memory requirements for raw encoder.
 LZMA_API (lzma_ret) lzma_raw_encoder(lzma_stream *strm
 Initialize raw encoder.

Variables

const lzma_filter *filters lzma_attr_warn_unused_result
lzma_allocatorallocator
lzma_allocator const uint8_t * in
lzma_allocator const uint8_t size_t in_size
lzma_allocator const uint8_t
size_t uint8_t * 
out
lzma_allocator const uint8_t
size_t uint8_t size_t * 
out_pos
lzma_allocator const uint8_t
size_t uint8_t size_t size_t 
out_size
lzma_allocator const uint8_t
size_t * 
in_pos
const lzma_filterfilter
uint8_t * props
lzma_allocator const uint8_t size_t props_size

Detailed Description

Common filter related types.

Author:
Copyright (C) 1999-2006 Igor Pavlov
Copyright (C) 2007 Lasse Collin

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.


Define Documentation

#define LZMA_FILTERS_MAX   4

Maximum number of filters in a chain.

A filter chain can have 1-4 filters, of which three are allowed to change the size of the data. Usually only one or two filters are needed.

Referenced by coder_add_filter(), and LZMA_API().


Function Documentation

LZMA_API ( lzma_bool   )  const

Test if the given Filter ID is supported for encoding.

Test if the given Filter ID is supported for decoding.

Returns 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.

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

Test if the given Filter ID is supported for encoding.

Test if the given Check ID is supported.

Compare if two Index lists are identical.

Locate a Record.

When the Index is available, it is possible to do random-access reading with granularity of Block size.

Parameters:
i Pointer to lzma_index structure
record Pointer to a structure to hold the search results
target Uncompressed target offset which the caller would like to locate from the Stream

If the target is smaller than the uncompressed size of the Stream (can be checked with lzma_index_uncompressed_size()):

  • Information about the Record containing the requested uncompressed offset is stored into *record.
  • Read offset will be adjusted so that calling lzma_index_read() can be used to read subsequent Records.
  • This function returns false.

If target is greater than the uncompressed size of the Stream, *record and the read position are not modified, and this function returns true.

Returns:
True if *a and *b are equal, false otherwise.

Test if the given Filter ID is supported for encoding.

Test if the given Check ID is supported.

Set a compression preset to lzma_options_lzma structure.

Test if given compression mode is supported.

Returns true if the given match finder is supported by this liblzma build. Otherwise false is returned. It is safe to call this with a value that isn't listed in lzma_match_finder enumeration; the return value will be false.

There is no way to list which match finders are available in this particular liblzma version and build. It would be useless, because a new match finder, which the application developer wasn't aware, could require giving additional options to the encoder that the older match finders don't need.

Returns true if the given compression mode is supported by this liblzma build. Otherwise false is returned. It is safe to call this with a value that isn't listed in lzma_mode enumeration; the return value will be false.

There is no way to list which modes are available in this particular liblzma version and build. It would be useless, because a new compression mode, which the application developer wasn't aware, could require giving additional options to the encoder that the older modes don't need.

0 is the fastest and 9 is the slowest. These match the switches -0 .. -9 of the xz command line tool. In addition, it is possible to bitwise-or flags to the preset. Currently only LZMA_PRESET_EXTREME is supported. The flags are defined in container.h, because the flags are used also with lzma_easy_encoder().

The preset values are subject to changes between liblzma versions.

This function is available only if LZMA1 or LZMA2 encoder has been enabled when building liblzma.

References init_current(), next_group(), previous_group(), and set_info().

LZMA_API ( uint64_t   )  const

Calculate rough memory requirements for raw encoder.

Calculate rough memory requirements for raw decoder.

Parameters:
filters Array of filters terminated with .id == LZMA_VLI_UNKNOWN.
Returns:
Rough number of bytes required for the given filter chain when encoding.
Parameters:
filters Array of filters terminated with .id == LZMA_VLI_UNKNOWN.
Returns:
Rough number of bytes required for the given filter chain when decoding.

Calculate rough memory requirements for raw encoder.

Calculate Unpadded Size.

Get the memory usage of decoder filter chain.

Calculates CRC64 using the polynomial from the ECMA-182 standard.

This function is used similarly to lzma_crc32(). See its documentation.

LZMA_API ( lzma_ret   ) 

Initialize raw encoder.

Decode Filter Flags from given buffer.

Encode Filter Flags into given buffer.

Calculate encoded size of a Filter Flags field.

Decode the Filter Properties field.

Encode the Filter Properties field.

Get the size of the Filter Properties field.

Single-call raw decoder.

Single-call raw encoder.

Initialize raw decoder.

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 minimum number of filters is one and the maximum is four.

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

The initialization of raw decoder goes similarly to raw encoder.

The `action' with lzma_code() can be LZMA_RUN or LZMA_FINISH. Using LZMA_FINISH is not required, it is supported just for convenience.

Returns:
- LZMA_OK
  • LZMA_MEM_ERROR
  • LZMA_OPTIONS_ERROR
  • LZMA_PROG_ERROR
Parameters:
allocator lzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
in Beginning of the input buffer
in_size Size of the input buffer
out Beginning of the output buffer
out_pos The next byte will be written to out[*out_pos]. *out_pos is updated only if encoding succeeds.
out_size Size of the out buffer; the first byte into which no data is written to is out[out_size].
Returns:
- LZMA_OK: Encoding was successful.
  • LZMA_BUF_ERROR: Not enough output buffer space.
  • LZMA_OPTIONS_ERROR
  • LZMA_MEM_ERROR
  • LZMA_DATA_ERROR
  • LZMA_PROG_ERROR
Parameters:
allocator lzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
in Beginning of the input buffer
in_pos The next byte will be read from in[*in_pos]. *in_pos is updated only if decoding succeeds.
in_size Size of the input buffer; the first byte that won't be read is in[in_size].
out Beginning of the output buffer
out_pos The next byte will be written to out[*out_pos]. *out_pos is updated only if encoding succeeds.
out_size Size of the out buffer; the first byte into which no data is written to is out[out_size].

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 propeties 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.
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.
It is OK to skip calling this function if lzma_properties_size() indicated that the size of the Filter Properties field is zero.
Parameters:
filter filter->id must have been set to the correct Filter ID. filter->options doesn't need to be initialized (it's not freed by this function). The decoded options will be stored to filter->options. filter->options is set to NULL if there are no properties or if an error occurs.
allocator Custom memory allocator used to allocate the options. Set to NULL to use the default malloc(), and in case of an error, also free().
props Input buffer containing the properties.
props_size Size of the properties. This must be the exact size; giving too much or too little input will return LZMA_OPTIONS_ERROR.
Returns:
- LZMA_OK
  • LZMA_OPTIONS_ERROR
  • LZMA_MEM_ERROR

Knowing the size of Filter Flags is useful to know when allocating memory to hold the encoded Filter Flags.

Parameters:
size Pointer to integer to hold the calculated size
filters Filter ID and associated options whose encoded size is to be calculted
Returns:
- LZMA_OK: *size set successfully. Note that this doesn't guarantee that filters->options is valid, thus lzma_filter_flags_encode() may still fail.
  • LZMA_OPTIONS_ERROR: Unknown Filter ID or unsupported options.
  • LZMA_PROG_ERROR: Invalid options
Note:
If you need to calculate size of List of Filter Flags, you need to loop over every lzma_filter entry.

In contrast to some functions, this doesn't allocate the needed buffer. This is due to how this function is used internally by liblzma.

Parameters:
filters Filter ID and options to be encoded
out Beginning of the output buffer
out_pos out[*out_pos] is the next write position. This is updated by the encoder.
out_size out[out_size] is the first byte to not write.
Returns:
- LZMA_OK: Encoding was successful.
  • LZMA_OPTIONS_ERROR: Invalid or unsupported options.
  • LZMA_PROG_ERROR: Invalid options or not enough output buffer space (you should have checked it with lzma_filter_flags_size()).

The decoded result is stored into *filters. filters->options is initialized but the old value is NOT free()d.

Returns:
- LZMA_OK
  • LZMA_OPTIONS_ERROR
  • LZMA_MEM_ERROR
  • LZMA_PROG_ERROR

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