OLD | NEW |
(Empty) | |
| 1 /** |
| 2 * \file lzma/filter.h |
| 3 * \brief Common filter related types |
| 4 */ |
| 5 |
| 6 /* |
| 7 * Author: Lasse Collin |
| 8 * |
| 9 * This file has been put into the public domain. |
| 10 * You can do whatever you want with this file. |
| 11 * |
| 12 * See ../lzma.h for information about liblzma as a whole. |
| 13 */ |
| 14 |
| 15 #ifndef LZMA_H_INTERNAL |
| 16 # error Never include this file directly. Use <lzma.h> instead. |
| 17 #endif |
| 18 |
| 19 |
| 20 /** |
| 21 * \brief Maximum number of filters in a chain |
| 22 * |
| 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. |
| 25 */ |
| 26 #define LZMA_FILTERS_MAX 4 |
| 27 |
| 28 |
| 29 /** |
| 30 * \brief Filter options |
| 31 * |
| 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. |
| 35 * |
| 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. |
| 42 */ |
| 43 typedef struct { |
| 44 /** |
| 45 * \brief Filter ID |
| 46 * |
| 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. |
| 50 * |
| 51 * \note This is not an enum, because on some systems enums |
| 52 * cannot be 64-bit. |
| 53 */ |
| 54 lzma_vli id; |
| 55 |
| 56 /** |
| 57 * \brief Pointer to filter-specific options structure |
| 58 * |
| 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. |
| 62 * |
| 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. |
| 67 */ |
| 68 void *options; |
| 69 |
| 70 } lzma_filter; |
| 71 |
| 72 |
| 73 /** |
| 74 * \brief Test if the given Filter ID is supported for encoding |
| 75 * |
| 76 * Return true if the give Filter ID is supported for encoding by this |
| 77 * liblzma build. Otherwise false is returned. |
| 78 * |
| 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. |
| 82 */ |
| 83 extern LZMA_API(lzma_bool) lzma_filter_encoder_is_supported(lzma_vli id) |
| 84 lzma_nothrow lzma_attr_const; |
| 85 |
| 86 |
| 87 /** |
| 88 * \brief Test if the given Filter ID is supported for decoding |
| 89 * |
| 90 * Return true if the give Filter ID is supported for decoding by this |
| 91 * liblzma build. Otherwise false is returned. |
| 92 */ |
| 93 extern LZMA_API(lzma_bool) lzma_filter_decoder_is_supported(lzma_vli id) |
| 94 lzma_nothrow lzma_attr_const; |
| 95 |
| 96 |
| 97 /** |
| 98 * \brief Copy the filters array |
| 99 * |
| 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. |
| 105 * |
| 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. |
| 111 * |
| 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. |
| 114 * |
| 115 * If an error occurs, memory possibly already allocated by this function |
| 116 * is always freed. |
| 117 * |
| 118 * \return - LZMA_OK |
| 119 * - LZMA_MEM_ERROR |
| 120 * - LZMA_OPTIONS_ERROR: Unsupported Filter ID and its options |
| 121 * is not NULL. |
| 122 * - LZMA_PROG_ERROR: src or dest is NULL. |
| 123 */ |
| 124 extern LZMA_API(lzma_ret) lzma_filters_copy(const lzma_filter *src, |
| 125 lzma_filter *dest, lzma_allocator *allocator) lzma_nothrow; |
| 126 |
| 127 |
| 128 /** |
| 129 * \brief Calculate rough memory requirements for raw encoder |
| 130 * |
| 131 * Because the calculation is rough, this function can be used to calculate |
| 132 * the memory requirements for Block and Stream encoders too. |
| 133 * |
| 134 * \param filters Array of filters terminated with |
| 135 * .id == LZMA_VLI_UNKNOWN. |
| 136 * |
| 137 * \return Rough number of bytes of memory required for the given |
| 138 * filter chain when encoding. |
| 139 */ |
| 140 extern LZMA_API(uint64_t) lzma_raw_encoder_memusage(const lzma_filter *filters) |
| 141 lzma_nothrow lzma_attr_pure; |
| 142 |
| 143 |
| 144 /** |
| 145 * \brief Calculate rough memory requirements for raw decoder |
| 146 * |
| 147 * Because the calculation is rough, this function can be used to calculate |
| 148 * the memory requirements for Block and Stream decoders too. |
| 149 * |
| 150 * \param filters Array of filters terminated with |
| 151 * .id == LZMA_VLI_UNKNOWN. |
| 152 * |
| 153 * \return Rough number of bytes of memory required for the given |
| 154 * filter chain when decoding. |
| 155 */ |
| 156 extern LZMA_API(uint64_t) lzma_raw_decoder_memusage(const lzma_filter *filters) |
| 157 lzma_nothrow lzma_attr_pure; |
| 158 |
| 159 |
| 160 /** |
| 161 * \brief Initialize raw encoder |
| 162 * |
| 163 * This function may be useful when implementing custom file formats. |
| 164 * |
| 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. |
| 168 * |
| 169 * The `action' with lzma_code() can be LZMA_RUN, LZMA_SYNC_FLUSH (if the |
| 170 * filter chain supports it), or LZMA_FINISH. |
| 171 * |
| 172 * \return - LZMA_OK |
| 173 * - LZMA_MEM_ERROR |
| 174 * - LZMA_OPTIONS_ERROR |
| 175 * - LZMA_PROG_ERROR |
| 176 */ |
| 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; |
| 180 |
| 181 |
| 182 /** |
| 183 * \brief Initialize raw decoder |
| 184 * |
| 185 * The initialization of raw decoder goes similarly to raw encoder. |
| 186 * |
| 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. |
| 189 * |
| 190 * \return - LZMA_OK |
| 191 * - LZMA_MEM_ERROR |
| 192 * - LZMA_OPTIONS_ERROR |
| 193 * - LZMA_PROG_ERROR |
| 194 */ |
| 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; |
| 198 |
| 199 |
| 200 /** |
| 201 * \brief Update the filter chain in the encoder |
| 202 * |
| 203 * This function is for advanced users only. This function has two slightly |
| 204 * different purposes: |
| 205 * |
| 206 * - After LZMA_FULL_FLUSH when using Stream encoder: Set a new filter |
| 207 * chain, which will be used starting from the next Block. |
| 208 * |
| 209 * - After LZMA_SYNC_FLUSH using Raw, Block, or Stream encoder: Change |
| 210 * the filter-specific options in the middle of encoding. The actual |
| 211 * filters in the chain (Filter IDs) cannot be changed. In the future, |
| 212 * it might become possible to change the filter options without |
| 213 * using LZMA_SYNC_FLUSH. |
| 214 * |
| 215 * While rarely useful, this function may be called also when no data has |
| 216 * been compressed yet. In that case, this function will behave as if |
| 217 * LZMA_FULL_FLUSH (Stream encoder) or LZMA_SYNC_FLUSH (Raw or Block |
| 218 * encoder) had been used right before calling this function. |
| 219 * |
| 220 * \return - LZMA_OK |
| 221 * - LZMA_MEM_ERROR |
| 222 * - LZMA_MEMLIMIT_ERROR |
| 223 * - LZMA_OPTIONS_ERROR |
| 224 * - LZMA_PROG_ERROR |
| 225 */ |
| 226 extern LZMA_API(lzma_ret) lzma_filters_update( |
| 227 lzma_stream *strm, const lzma_filter *filters) lzma_nothrow; |
| 228 |
| 229 |
| 230 /** |
| 231 * \brief Single-call raw encoder |
| 232 * |
| 233 * \param filters Array of lzma_filter structures. The end of the |
| 234 * array must be marked with .id = LZMA_VLI_UNKNOWN. |
| 235 * \param allocator lzma_allocator for custom allocator functions. |
| 236 * Set to NULL to use malloc() and free(). |
| 237 * \param in Beginning of the input buffer |
| 238 * \param in_size Size of the input buffer |
| 239 * \param out Beginning of the output buffer |
| 240 * \param out_pos The next byte will be written to out[*out_pos]. |
| 241 * *out_pos is updated only if encoding succeeds. |
| 242 * \param out_size Size of the out buffer; the first byte into |
| 243 * which no data is written to is out[out_size]. |
| 244 * |
| 245 * \return - LZMA_OK: Encoding was successful. |
| 246 * - LZMA_BUF_ERROR: Not enough output buffer space. |
| 247 * - LZMA_OPTIONS_ERROR |
| 248 * - LZMA_MEM_ERROR |
| 249 * - LZMA_DATA_ERROR |
| 250 * - LZMA_PROG_ERROR |
| 251 * |
| 252 * \note There is no function to calculate how big output buffer |
| 253 * would surely be big enough. (lzma_stream_buffer_bound() |
| 254 * works only for lzma_stream_buffer_encode().) |
| 255 */ |
| 256 extern LZMA_API(lzma_ret) lzma_raw_buffer_encode( |
| 257 const lzma_filter *filters, lzma_allocator *allocator, |
| 258 const uint8_t *in, size_t in_size, uint8_t *out, |
| 259 size_t *out_pos, size_t out_size) lzma_nothrow; |
| 260 |
| 261 |
| 262 /** |
| 263 * \brief Single-call raw decoder |
| 264 * |
| 265 * \param filters Array of lzma_filter structures. The end of the |
| 266 * array must be marked with .id = LZMA_VLI_UNKNOWN. |
| 267 * \param allocator lzma_allocator for custom allocator functions. |
| 268 * Set to NULL to use malloc() and free(). |
| 269 * \param in Beginning of the input buffer |
| 270 * \param in_pos The next byte will be read from in[*in_pos]. |
| 271 * *in_pos is updated only if decoding succeeds. |
| 272 * \param in_size Size of the input buffer; the first byte that |
| 273 * won't be read is in[in_size]. |
| 274 * \param out Beginning of the output buffer |
| 275 * \param out_pos The next byte will be written to out[*out_pos]. |
| 276 * *out_pos is updated only if encoding succeeds. |
| 277 * \param out_size Size of the out buffer; the first byte into |
| 278 * which no data is written to is out[out_size]. |
| 279 */ |
| 280 extern LZMA_API(lzma_ret) lzma_raw_buffer_decode( |
| 281 const lzma_filter *filters, lzma_allocator *allocator, |
| 282 const uint8_t *in, size_t *in_pos, size_t in_size, |
| 283 uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow; |
| 284 |
| 285 |
| 286 /** |
| 287 * \brief Get the size of the Filter Properties field |
| 288 * |
| 289 * This function may be useful when implementing custom file formats |
| 290 * using the raw encoder and decoder. |
| 291 * |
| 292 * \param size Pointer to uint32_t to hold the size of the properties |
| 293 * \param filter Filter ID and options (the size of the properties may |
| 294 * vary depending on the options) |
| 295 * |
| 296 * \return - LZMA_OK |
| 297 * - LZMA_OPTIONS_ERROR |
| 298 * - LZMA_PROG_ERROR |
| 299 * |
| 300 * \note This function validates the Filter ID, but does not |
| 301 * necessarily validate the options. Thus, it is possible |
| 302 * that this returns LZMA_OK while the following call to |
| 303 * lzma_properties_encode() returns LZMA_OPTIONS_ERROR. |
| 304 */ |
| 305 extern LZMA_API(lzma_ret) lzma_properties_size( |
| 306 uint32_t *size, const lzma_filter *filter) lzma_nothrow; |
| 307 |
| 308 |
| 309 /** |
| 310 * \brief Encode the Filter Properties field |
| 311 * |
| 312 * \param filter Filter ID and options |
| 313 * \param props Buffer to hold the encoded options. The size of |
| 314 * buffer must have been already determined with |
| 315 * lzma_properties_size(). |
| 316 * |
| 317 * \return - LZMA_OK |
| 318 * - LZMA_OPTIONS_ERROR |
| 319 * - LZMA_PROG_ERROR |
| 320 * |
| 321 * \note Even this function won't validate more options than actually |
| 322 * necessary. Thus, it is possible that encoding the properties |
| 323 * succeeds but using the same options to initialize the encoder |
| 324 * will fail. |
| 325 * |
| 326 * \note It is OK to skip calling this function if |
| 327 * lzma_properties_size() indicated that the size |
| 328 * of the Filter Properties field is zero. |
| 329 */ |
| 330 extern LZMA_API(lzma_ret) lzma_properties_encode( |
| 331 const lzma_filter *filter, uint8_t *props) lzma_nothrow; |
| 332 |
| 333 |
| 334 /** |
| 335 * \brief Decode the Filter Properties field |
| 336 * |
| 337 * \param filter filter->id must have been set to the correct |
| 338 * Filter ID. filter->options doesn't need to be |
| 339 * initialized (it's not freed by this function). The |
| 340 * decoded options will be stored to filter->options. |
| 341 * filter->options is set to NULL if there are no |
| 342 * properties or if an error occurs. |
| 343 * \param allocator Custom memory allocator used to allocate the |
| 344 * options. Set to NULL to use the default malloc(), |
| 345 * and in case of an error, also free(). |
| 346 * \param props Input buffer containing the properties. |
| 347 * \param props_size Size of the properties. This must be the exact |
| 348 * size; giving too much or too little input will |
| 349 * return LZMA_OPTIONS_ERROR. |
| 350 * |
| 351 * \return - LZMA_OK |
| 352 * - LZMA_OPTIONS_ERROR |
| 353 * - LZMA_MEM_ERROR |
| 354 */ |
| 355 extern LZMA_API(lzma_ret) lzma_properties_decode( |
| 356 lzma_filter *filter, lzma_allocator *allocator, |
| 357 const uint8_t *props, size_t props_size) lzma_nothrow; |
| 358 |
| 359 |
| 360 /** |
| 361 * \brief Calculate encoded size of a Filter Flags field |
| 362 * |
| 363 * Knowing the size of Filter Flags is useful to know when allocating |
| 364 * memory to hold the encoded Filter Flags. |
| 365 * |
| 366 * \param size Pointer to integer to hold the calculated size |
| 367 * \param filters Filter ID and associated options whose encoded |
| 368 * size is to be calculated |
| 369 * |
| 370 * \return - LZMA_OK: *size set successfully. Note that this doesn't |
| 371 * guarantee that filters->options is valid, thus |
| 372 * lzma_filter_flags_encode() may still fail. |
| 373 * - LZMA_OPTIONS_ERROR: Unknown Filter ID or unsupported options. |
| 374 * - LZMA_PROG_ERROR: Invalid options |
| 375 * |
| 376 * \note If you need to calculate size of List of Filter Flags, |
| 377 * you need to loop over every lzma_filter entry. |
| 378 */ |
| 379 extern LZMA_API(lzma_ret) lzma_filter_flags_size( |
| 380 uint32_t *size, const lzma_filter *filters) |
| 381 lzma_nothrow lzma_attr_warn_unused_result; |
| 382 |
| 383 |
| 384 /** |
| 385 * \brief Encode Filter Flags into given buffer |
| 386 * |
| 387 * In contrast to some functions, this doesn't allocate the needed buffer. |
| 388 * This is due to how this function is used internally by liblzma. |
| 389 * |
| 390 * \param filters Filter ID and options to be encoded |
| 391 * \param out Beginning of the output buffer |
| 392 * \param out_pos out[*out_pos] is the next write position. This |
| 393 * is updated by the encoder. |
| 394 * \param out_size out[out_size] is the first byte to not write. |
| 395 * |
| 396 * \return - LZMA_OK: Encoding was successful. |
| 397 * - LZMA_OPTIONS_ERROR: Invalid or unsupported options. |
| 398 * - LZMA_PROG_ERROR: Invalid options or not enough output |
| 399 * buffer space (you should have checked it with |
| 400 * lzma_filter_flags_size()). |
| 401 */ |
| 402 extern LZMA_API(lzma_ret) lzma_filter_flags_encode(const lzma_filter *filters, |
| 403 uint8_t *out, size_t *out_pos, size_t out_size) |
| 404 lzma_nothrow lzma_attr_warn_unused_result; |
| 405 |
| 406 |
| 407 /** |
| 408 * \brief Decode Filter Flags from given buffer |
| 409 * |
| 410 * The decoded result is stored into *filters. filters->options is |
| 411 * initialized but the old value is NOT free()d. |
| 412 * |
| 413 * \return - LZMA_OK |
| 414 * - LZMA_OPTIONS_ERROR |
| 415 * - LZMA_MEM_ERROR |
| 416 * - LZMA_PROG_ERROR |
| 417 */ |
| 418 extern LZMA_API(lzma_ret) lzma_filter_flags_decode( |
| 419 lzma_filter *filters, lzma_allocator *allocator, |
| 420 const uint8_t *in, size_t *in_pos, size_t in_size) |
| 421 lzma_nothrow lzma_attr_warn_unused_result; |
OLD | NEW |