3 * \brief Common filter related types
9 * This file has been put into the public domain.
10 * You can do whatever you want with this file.
12 * See ../lzma.h for information about liblzma as a whole.
15 #ifndef LZMA_H_INTERNAL
16 # error Never include this file directly. Use <lzma.h> instead.
21 * \brief Maximum number of filters in a chain
23 * A filter chain can have 1-4 filters, of which three are allowed to change
24 * the size of the data. Usually only one or two filters are needed.
26 #define LZMA_FILTERS_MAX 4
30 * \brief Filter options
32 * This structure is used to pass Filter ID and a pointer filter's
33 * options to liblzma. A few functions work with a single lzma_filter
34 * structure, while most functions expect a filter chain.
36 * A filter chain is indicated with an array of lzma_filter structures.
37 * The array is terminated with .id = LZMA_VLI_UNKNOWN. Thus, the filter
38 * array must have LZMA_FILTERS_MAX + 1 elements (that is, five) to
39 * be able to hold any arbitrary filter chain. This is important when
40 * using lzma_block_header_decode() from block.h, because too small
41 * array would make liblzma write past the end of the filters array.
47 * Use constants whose name begin with `LZMA_FILTER_' to specify
48 * different filters. In an array of lzma_filter structures, use
49 * LZMA_VLI_UNKNOWN to indicate end of filters.
51 * \note This is not an enum, because on some systems enums
57 * \brief Pointer to filter-specific options structure
59 * If the filter doesn't need options, set this to NULL. If id is
60 * set to LZMA_VLI_UNKNOWN, options is ignored, and thus
61 * doesn't need be initialized.
63 * Some filters support changing the options in the middle of
64 * the encoding process. These filters store the pointer of the
65 * options structure and communicate with the application via
66 * modifications of the options structure.
74 * \brief Test if the given Filter ID is supported for encoding
76 * Return true if the give Filter ID is supported for encoding by this
77 * liblzma build. Otherwise false is returned.
79 * There is no way to list which filters are available in this particular
80 * liblzma version and build. It would be useless, because the application
81 * couldn't know what kind of options the filter would need.
83 extern LZMA_API(lzma_bool) lzma_filter_encoder_is_supported(lzma_vli id)
84 lzma_nothrow lzma_attr_const;
88 * \brief Test if the given Filter ID is supported for decoding
90 * Return true if the give Filter ID is supported for decoding by this
91 * liblzma build. Otherwise false is returned.
93 extern LZMA_API(lzma_bool) lzma_filter_decoder_is_supported(lzma_vli id)
94 lzma_nothrow lzma_attr_const;
98 * \brief Calculate rough memory requirements for raw encoder
100 * Because the calculation is rough, this function can be used to calculate
101 * the memory requirements for Block and Stream encoders too.
103 * \param filters Array of filters terminated with
104 * .id == LZMA_VLI_UNKNOWN.
106 * \return Rough number of bytes of memory required for the given
107 * filter chain when encoding.
109 extern LZMA_API(uint64_t) lzma_raw_encoder_memusage(const lzma_filter *filters)
110 lzma_nothrow lzma_attr_pure;
114 * \brief Calculate rough memory requirements for raw decoder
116 * Because the calculation is rough, this function can be used to calculate
117 * the memory requirements for Block and Stream decoders too.
119 * \param filters Array of filters terminated with
120 * .id == LZMA_VLI_UNKNOWN.
122 * \return Rough number of bytes of memory required for the given
123 * filter chain when decoding.
125 extern LZMA_API(uint64_t) lzma_raw_decoder_memusage(const lzma_filter *filters)
126 lzma_nothrow lzma_attr_pure;
130 * \brief Initialize raw encoder
132 * This function may be useful when implementing custom file formats.
134 * \param strm Pointer to properly prepared lzma_stream
135 * \param filters Array of lzma_filter structures. The end of the
136 * array must be marked with .id = LZMA_VLI_UNKNOWN.
138 * The `action' with lzma_code() can be LZMA_RUN, LZMA_SYNC_FLUSH (if the
139 * filter chain supports it), or LZMA_FINISH.
143 * - LZMA_OPTIONS_ERROR
146 extern LZMA_API(lzma_ret) lzma_raw_encoder(
147 lzma_stream *strm, const lzma_filter *filters)
148 lzma_nothrow lzma_attr_warn_unused_result;
152 * \brief Initialize raw decoder
154 * The initialization of raw decoder goes similarly to raw encoder.
156 * The `action' with lzma_code() can be LZMA_RUN or LZMA_FINISH. Using
157 * LZMA_FINISH is not required, it is supported just for convenience.
161 * - LZMA_OPTIONS_ERROR
164 extern LZMA_API(lzma_ret) lzma_raw_decoder(
165 lzma_stream *strm, const lzma_filter *filters)
166 lzma_nothrow lzma_attr_warn_unused_result;
170 * \brief Single-call raw encoder
172 * \param filters Array of lzma_filter structures. The end of the
173 * array must be marked with .id = LZMA_VLI_UNKNOWN.
174 * \param allocator lzma_allocator for custom allocator functions.
175 * Set to NULL to use malloc() and free().
176 * \param in Beginning of the input buffer
177 * \param in_size Size of the input buffer
178 * \param out Beginning of the output buffer
179 * \param out_pos The next byte will be written to out[*out_pos].
180 * *out_pos is updated only if encoding succeeds.
181 * \param out_size Size of the out buffer; the first byte into
182 * which no data is written to is out[out_size].
184 * \return - LZMA_OK: Encoding was successful.
185 * - LZMA_BUF_ERROR: Not enough output buffer space.
186 * - LZMA_OPTIONS_ERROR
191 * \note There is no function to calculate how big output buffer
192 * would surely be big enough. (lzma_stream_buffer_bound()
193 * works only for lzma_stream_buffer_encode().)
195 extern LZMA_API(lzma_ret) lzma_raw_buffer_encode(
196 const lzma_filter *filters, lzma_allocator *allocator,
197 const uint8_t *in, size_t in_size, uint8_t *out,
198 size_t *out_pos, size_t out_size) lzma_nothrow;
202 * \brief Single-call raw decoder
204 * \param filters Array of lzma_filter structures. The end of the
205 * array must be marked with .id = LZMA_VLI_UNKNOWN.
206 * \param allocator lzma_allocator for custom allocator functions.
207 * Set to NULL to use malloc() and free().
208 * \param in Beginning of the input buffer
209 * \param in_pos The next byte will be read from in[*in_pos].
210 * *in_pos is updated only if decoding succeeds.
211 * \param in_size Size of the input buffer; the first byte that
212 * won't be read is in[in_size].
213 * \param out Beginning of the output buffer
214 * \param out_pos The next byte will be written to out[*out_pos].
215 * *out_pos is updated only if encoding succeeds.
216 * \param out_size Size of the out buffer; the first byte into
217 * which no data is written to is out[out_size].
219 extern LZMA_API(lzma_ret) lzma_raw_buffer_decode(
220 const lzma_filter *filters, lzma_allocator *allocator,
221 const uint8_t *in, size_t *in_pos, size_t in_size,
222 uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow;
226 * \brief Get the size of the Filter Properties field
228 * This function may be useful when implementing custom file formats
229 * using the raw encoder and decoder.
231 * \param size Pointer to uint32_t to hold the size of the properties
232 * \param filter Filter ID and options (the size of the propeties may
233 * vary depending on the options)
236 * - LZMA_OPTIONS_ERROR
239 * \note This function validates the Filter ID, but does not
240 * necessarily validate the options. Thus, it is possible
241 * that this returns LZMA_OK while the following call to
242 * lzma_properties_encode() returns LZMA_OPTIONS_ERROR.
244 extern LZMA_API(lzma_ret) lzma_properties_size(
245 uint32_t *size, const lzma_filter *filter) lzma_nothrow;
249 * \brief Encode the Filter Properties field
251 * \param filter Filter ID and options
252 * \param props Buffer to hold the encoded options. The size of
253 * buffer must have been already determined with
254 * lzma_properties_size().
257 * - LZMA_OPTIONS_ERROR
260 * \note Even this function won't validate more options than actually
261 * necessary. Thus, it is possible that encoding the properties
262 * succeeds but using the same options to initialize the encoder
265 * \note It is OK to skip calling this function if
266 * lzma_properties_size() indicated that the size
267 * of the Filter Properties field is zero.
269 extern LZMA_API(lzma_ret) lzma_properties_encode(
270 const lzma_filter *filter, uint8_t *props) lzma_nothrow;
274 * \brief Decode the Filter Properties field
276 * \param filter filter->id must have been set to the correct
277 * Filter ID. filter->options doesn't need to be
278 * initialized (it's not freed by this function). The
279 * decoded options will be stored to filter->options.
280 * filter->options is set to NULL if there are no
281 * properties or if an error occurs.
282 * \param allocator Custom memory allocator used to allocate the
283 * options. Set to NULL to use the default malloc(),
284 * and in case of an error, also free().
285 * \param props Input buffer containing the properties.
286 * \param props_size Size of the properties. This must be the exact
287 * size; giving too much or too little input will
288 * return LZMA_OPTIONS_ERROR.
291 * - LZMA_OPTIONS_ERROR
294 extern LZMA_API(lzma_ret) lzma_properties_decode(
295 lzma_filter *filter, lzma_allocator *allocator,
296 const uint8_t *props, size_t props_size) lzma_nothrow;
300 * \brief Calculate encoded size of a Filter Flags field
302 * Knowing the size of Filter Flags is useful to know when allocating
303 * memory to hold the encoded Filter Flags.
305 * \param size Pointer to integer to hold the calculated size
306 * \param filters Filter ID and associated options whose encoded
307 * size is to be calculted
309 * \return - LZMA_OK: *size set successfully. Note that this doesn't
310 * guarantee that filters->options is valid, thus
311 * lzma_filter_flags_encode() may still fail.
312 * - LZMA_OPTIONS_ERROR: Unknown Filter ID or unsupported options.
313 * - LZMA_PROG_ERROR: Invalid options
315 * \note If you need to calculate size of List of Filter Flags,
316 * you need to loop over every lzma_filter entry.
318 extern LZMA_API(lzma_ret) lzma_filter_flags_size(
319 uint32_t *size, const lzma_filter *filters)
320 lzma_nothrow lzma_attr_warn_unused_result;
324 * \brief Encode Filter Flags into given buffer
326 * In contrast to some functions, this doesn't allocate the needed buffer.
327 * This is due to how this function is used internally by liblzma.
329 * \param filters Filter ID and options to be encoded
330 * \param out Beginning of the output buffer
331 * \param out_pos out[*out_pos] is the next write position. This
332 * is updated by the encoder.
333 * \param out_size out[out_size] is the first byte to not write.
335 * \return - LZMA_OK: Encoding was successful.
336 * - LZMA_OPTIONS_ERROR: Invalid or unsupported options.
337 * - LZMA_PROG_ERROR: Invalid options or not enough output
338 * buffer space (you should have checked it with
339 * lzma_filter_flags_size()).
341 extern LZMA_API(lzma_ret) lzma_filter_flags_encode(const lzma_filter *filters,
342 uint8_t *out, size_t *out_pos, size_t out_size)
343 lzma_nothrow lzma_attr_warn_unused_result;
347 * \brief Decode Filter Flags from given buffer
349 * The decoded result is stored into *filters. filters->options is
350 * initialized but the old value is NOT free()d.
353 * - LZMA_OPTIONS_ERROR
357 extern LZMA_API(lzma_ret) lzma_filter_flags_decode(
358 lzma_filter *filters, lzma_allocator *allocator,
359 const uint8_t *in, size_t *in_pos, size_t in_size)
360 lzma_nothrow lzma_attr_warn_unused_result;