3 * \brief Common filter related types
5 * \author Copyright (C) 1999-2006 Igor Pavlov
6 * \author Copyright (C) 2007 Lasse Collin
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2.1 of the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
19 #ifndef LZMA_H_INTERNAL
20 # error Never include this file directly. Use <lzma.h> instead.
25 * \brief Filter options
27 * This structure is used to pass Filter ID and a pointer filter's options
34 * Use constants whose name begin with `LZMA_FILTER_' to specify
35 * different filters. In an array of lzma_option_filter structures,
36 * use LZMA_VLI_VALUE_UNKNOWN to indicate end of filters.
41 * \brief Pointer to filter-specific options structure
43 * If the filter doesn't need options, set this to NULL. If id is
44 * set to LZMA_VLI_VALUE_UNKNOWN, options is ignored, and thus
45 * doesn't need be initialized.
47 * Some filters support changing the options in the middle of
48 * the encoding process. These filters store the pointer of the
49 * options structure and communicate with the application via
50 * modifications of the options structure.
54 } lzma_options_filter;
58 * \brief Filters available for encoding
60 * Pointer to an array containing the list of available Filter IDs that
61 * can be used for encoding. The last element is LZMA_VLI_VALUE_UNKNOWN.
63 * If lzma_available_filter_encoders[0] == LZMA_VLI_VALUE_UNKNOWN, the
64 * encoder components haven't been built at all. This means that the
65 * encoding-specific functions are probably missing from the library
68 extern const lzma_vli *const lzma_available_filter_encoders;
72 * \brief Filters available for decoding
74 * Pointer to an array containing the list of available Filter IDs that
75 * can be used for decoding. The last element is LZMA_VLI_VALUE_UNKNOWN.
77 * If lzma_available_filter_decoders[0] == LZMA_VLI_VALUE_UNKNOWN, the
78 * decoder components haven't been built at all. This means that the
79 * decoding-specific functions are probably missing from the library
82 extern const lzma_vli *const lzma_available_filter_decoders;
86 * \brief Calculate rough memory requirements for given filter chain
88 * \param filters Array of filters terminated with
89 * .id == LZMA_VLI_VALUE_UNKNOWN.
90 * \param is_encoder Set to true when calculating memory requirements
91 * of an encoder; false for decoder.
93 * \return Number of mebibytes (MiB i.e. 2^20) required for the given
94 * encoder or decoder filter chain.
96 * \note If calculating memory requirements of encoder, lzma_init() or
97 * lzma_init_encoder() must have been called earlier. Similarly,
98 * if calculating memory requirements of decoder, lzma_init() or
99 * lzma_init_decoder() must have been called earlier.
101 extern uint32_t lzma_memory_usage(
102 const lzma_options_filter *filters, lzma_bool is_encoder);
106 * \brief Calculates encoded size of a Filter Flags field
108 * Knowing the size of Filter Flags is useful to know when allocating
109 * memory to hold the encoded Filter Flags.
111 * \param size Pointer to integer to hold the calculated size
112 * \param options Filter ID and associated options whose encoded
113 * size is to be calculted
115 * \return - LZMA_OK: *size set successfully. Note that this doesn't
116 * guarantee that options->options is valid, thus
117 * lzma_filter_flags_encode() may still fail.
118 * - LZMA_HEADER_ERROR: Unknown Filter ID or unsupported options.
119 * - LZMA_PROG_ERROR: Invalid options
121 * \note If you need to calculate size of List of Filter Flags,
122 * you need to loop over every lzma_options_filter entry.
124 extern lzma_ret lzma_filter_flags_size(
125 uint32_t *size, const lzma_options_filter *options);
129 * \brief Encodes Filter Flags into given buffer
131 * In contrast to some functions, this doesn't allocate the needed buffer.
132 * This is due to how this function is used internally by liblzma.
134 * \param out Beginning of the output buffer
135 * \param out_pos out[*out_pos] is the next write position. This
136 * is updated by the encoder.
137 * \param out_size out[out_size] is the first byte to not write.
138 * \param options Filter options to be encoded
140 * \return - LZMA_OK: Encoding was successful.
141 * - LZMA_HEADER_ERROR: Invalid or unsupported options.
142 * - LZMA_PROG_ERROR: Invalid options or not enough output
143 * buffer space (you should have checked it with
144 * lzma_filter_flags_size()).
146 extern lzma_ret lzma_filter_flags_encode(uint8_t *out, size_t *out_pos,
147 size_t out_size, const lzma_options_filter *options);
151 * \brief Initializes Filter Flags decoder
153 * The decoded result is stored into *options. options->options is
154 * initialized but the old value is NOT free()d.
156 * Because the results of this decoder are placed into *options,
157 * strm->next_in, strm->avail_in, and strm->total_in are not used
158 * when calling lzma_code(). The only valid action for lzma_code()
165 extern lzma_ret lzma_filter_flags_decode(
166 lzma_options_filter *options, lzma_allocator *allocator,
167 const uint8_t *in, size_t *in_pos, size_t in_size);