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 Copy the filters array
100 * Copy the Filter IDs and filter-specific options from src to dest.
101 * Up to LZMA_FILTERS_MAX filters are copied, plus the terminating
102 * .id == LZMA_VLI_UNKNOWN. Thus, dest should have at least
103 * LZMA_FILTERS_MAX + 1 elements space unless the caller knows that
104 * src is smaller than that.
106 * Unless the filter-specific options is NULL, the Filter ID has to be
107 * supported by liblzma, because liblzma needs to know the size of every
108 * filter-specific options structure. The filter-specific options are not
109 * validated. If options is NULL, any unsupported Filter IDs are copied
110 * without returning an error.
112 * Old filter-specific options in dest are not freed, so dest doesn't
113 * need to be initialized by the caller in any way.
115 * If an error occurs, memory possibly already allocated by this function
120 * - LZMA_OPTIONS_ERROR: Unsupported Filter ID and its options
122 * - LZMA_PROG_ERROR: src or dest is NULL.
124 extern LZMA_API(lzma_ret) lzma_filters_dup(const lzma_filter *src,
125 lzma_filter *dest, lzma_allocator *allocator);
129 * \brief Calculate rough memory requirements for raw encoder
131 * Because the calculation is rough, this function can be used to calculate
132 * the memory requirements for Block and Stream encoders too.
134 * \param filters Array of filters terminated with
135 * .id == LZMA_VLI_UNKNOWN.
137 * \return Rough number of bytes of memory required for the given
138 * filter chain when encoding.
140 extern LZMA_API(uint64_t) lzma_raw_encoder_memusage(const lzma_filter *filters)
141 lzma_nothrow lzma_attr_pure;
145 * \brief Calculate rough memory requirements for raw decoder
147 * Because the calculation is rough, this function can be used to calculate
148 * the memory requirements for Block and Stream decoders too.
150 * \param filters Array of filters terminated with
151 * .id == LZMA_VLI_UNKNOWN.
153 * \return Rough number of bytes of memory required for the given
154 * filter chain when decoding.
156 extern LZMA_API(uint64_t) lzma_raw_decoder_memusage(const lzma_filter *filters)
157 lzma_nothrow lzma_attr_pure;
161 * \brief Initialize raw encoder
163 * This function may be useful when implementing custom file formats.
165 * \param strm Pointer to properly prepared lzma_stream
166 * \param filters Array of lzma_filter structures. The end of the
167 * array must be marked with .id = LZMA_VLI_UNKNOWN.
169 * The `action' with lzma_code() can be LZMA_RUN, LZMA_SYNC_FLUSH (if the
170 * filter chain supports it), or LZMA_FINISH.
174 * - LZMA_OPTIONS_ERROR
177 extern LZMA_API(lzma_ret) lzma_raw_encoder(
178 lzma_stream *strm, const lzma_filter *filters)
179 lzma_nothrow lzma_attr_warn_unused_result;
183 * \brief Initialize raw decoder
185 * The initialization of raw decoder goes similarly to raw encoder.
187 * The `action' with lzma_code() can be LZMA_RUN or LZMA_FINISH. Using
188 * LZMA_FINISH is not required, it is supported just for convenience.
192 * - LZMA_OPTIONS_ERROR
195 extern LZMA_API(lzma_ret) lzma_raw_decoder(
196 lzma_stream *strm, const lzma_filter *filters)
197 lzma_nothrow lzma_attr_warn_unused_result;
201 * \brief Single-call raw encoder
203 * \param filters Array of lzma_filter structures. The end of the
204 * array must be marked with .id = LZMA_VLI_UNKNOWN.
205 * \param allocator lzma_allocator for custom allocator functions.
206 * Set to NULL to use malloc() and free().
207 * \param in Beginning of the input buffer
208 * \param in_size Size of the input buffer
209 * \param out Beginning of the output buffer
210 * \param out_pos The next byte will be written to out[*out_pos].
211 * *out_pos is updated only if encoding succeeds.
212 * \param out_size Size of the out buffer; the first byte into
213 * which no data is written to is out[out_size].
215 * \return - LZMA_OK: Encoding was successful.
216 * - LZMA_BUF_ERROR: Not enough output buffer space.
217 * - LZMA_OPTIONS_ERROR
222 * \note There is no function to calculate how big output buffer
223 * would surely be big enough. (lzma_stream_buffer_bound()
224 * works only for lzma_stream_buffer_encode().)
226 extern LZMA_API(lzma_ret) lzma_raw_buffer_encode(
227 const lzma_filter *filters, lzma_allocator *allocator,
228 const uint8_t *in, size_t in_size, uint8_t *out,
229 size_t *out_pos, size_t out_size) lzma_nothrow;
233 * \brief Single-call raw decoder
235 * \param filters Array of lzma_filter structures. The end of the
236 * array must be marked with .id = LZMA_VLI_UNKNOWN.
237 * \param allocator lzma_allocator for custom allocator functions.
238 * Set to NULL to use malloc() and free().
239 * \param in Beginning of the input buffer
240 * \param in_pos The next byte will be read from in[*in_pos].
241 * *in_pos is updated only if decoding succeeds.
242 * \param in_size Size of the input buffer; the first byte that
243 * won't be read is in[in_size].
244 * \param out Beginning of the output buffer
245 * \param out_pos The next byte will be written to out[*out_pos].
246 * *out_pos is updated only if encoding succeeds.
247 * \param out_size Size of the out buffer; the first byte into
248 * which no data is written to is out[out_size].
250 extern LZMA_API(lzma_ret) lzma_raw_buffer_decode(
251 const lzma_filter *filters, lzma_allocator *allocator,
252 const uint8_t *in, size_t *in_pos, size_t in_size,
253 uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow;
257 * \brief Get the size of the Filter Properties field
259 * This function may be useful when implementing custom file formats
260 * using the raw encoder and decoder.
262 * \param size Pointer to uint32_t to hold the size of the properties
263 * \param filter Filter ID and options (the size of the propeties may
264 * vary depending on the options)
267 * - LZMA_OPTIONS_ERROR
270 * \note This function validates the Filter ID, but does not
271 * necessarily validate the options. Thus, it is possible
272 * that this returns LZMA_OK while the following call to
273 * lzma_properties_encode() returns LZMA_OPTIONS_ERROR.
275 extern LZMA_API(lzma_ret) lzma_properties_size(
276 uint32_t *size, const lzma_filter *filter) lzma_nothrow;
280 * \brief Encode the Filter Properties field
282 * \param filter Filter ID and options
283 * \param props Buffer to hold the encoded options. The size of
284 * buffer must have been already determined with
285 * lzma_properties_size().
288 * - LZMA_OPTIONS_ERROR
291 * \note Even this function won't validate more options than actually
292 * necessary. Thus, it is possible that encoding the properties
293 * succeeds but using the same options to initialize the encoder
296 * \note It is OK to skip calling this function if
297 * lzma_properties_size() indicated that the size
298 * of the Filter Properties field is zero.
300 extern LZMA_API(lzma_ret) lzma_properties_encode(
301 const lzma_filter *filter, uint8_t *props) lzma_nothrow;
305 * \brief Decode the Filter Properties field
307 * \param filter filter->id must have been set to the correct
308 * Filter ID. filter->options doesn't need to be
309 * initialized (it's not freed by this function). The
310 * decoded options will be stored to filter->options.
311 * filter->options is set to NULL if there are no
312 * properties or if an error occurs.
313 * \param allocator Custom memory allocator used to allocate the
314 * options. Set to NULL to use the default malloc(),
315 * and in case of an error, also free().
316 * \param props Input buffer containing the properties.
317 * \param props_size Size of the properties. This must be the exact
318 * size; giving too much or too little input will
319 * return LZMA_OPTIONS_ERROR.
322 * - LZMA_OPTIONS_ERROR
325 extern LZMA_API(lzma_ret) lzma_properties_decode(
326 lzma_filter *filter, lzma_allocator *allocator,
327 const uint8_t *props, size_t props_size) lzma_nothrow;
331 * \brief Calculate encoded size of a Filter Flags field
333 * Knowing the size of Filter Flags is useful to know when allocating
334 * memory to hold the encoded Filter Flags.
336 * \param size Pointer to integer to hold the calculated size
337 * \param filters Filter ID and associated options whose encoded
338 * size is to be calculted
340 * \return - LZMA_OK: *size set successfully. Note that this doesn't
341 * guarantee that filters->options is valid, thus
342 * lzma_filter_flags_encode() may still fail.
343 * - LZMA_OPTIONS_ERROR: Unknown Filter ID or unsupported options.
344 * - LZMA_PROG_ERROR: Invalid options
346 * \note If you need to calculate size of List of Filter Flags,
347 * you need to loop over every lzma_filter entry.
349 extern LZMA_API(lzma_ret) lzma_filter_flags_size(
350 uint32_t *size, const lzma_filter *filters)
351 lzma_nothrow lzma_attr_warn_unused_result;
355 * \brief Encode Filter Flags into given buffer
357 * In contrast to some functions, this doesn't allocate the needed buffer.
358 * This is due to how this function is used internally by liblzma.
360 * \param filters Filter ID and options to be encoded
361 * \param out Beginning of the output buffer
362 * \param out_pos out[*out_pos] is the next write position. This
363 * is updated by the encoder.
364 * \param out_size out[out_size] is the first byte to not write.
366 * \return - LZMA_OK: Encoding was successful.
367 * - LZMA_OPTIONS_ERROR: Invalid or unsupported options.
368 * - LZMA_PROG_ERROR: Invalid options or not enough output
369 * buffer space (you should have checked it with
370 * lzma_filter_flags_size()).
372 extern LZMA_API(lzma_ret) lzma_filter_flags_encode(const lzma_filter *filters,
373 uint8_t *out, size_t *out_pos, size_t out_size)
374 lzma_nothrow lzma_attr_warn_unused_result;
378 * \brief Decode Filter Flags from given buffer
380 * The decoded result is stored into *filters. filters->options is
381 * initialized but the old value is NOT free()d.
384 * - LZMA_OPTIONS_ERROR
388 extern LZMA_API(lzma_ret) lzma_filter_flags_decode(
389 lzma_filter *filters, lzma_allocator *allocator,
390 const uint8_t *in, size_t *in_pos, size_t in_size)
391 lzma_nothrow lzma_attr_warn_unused_result;