filter.h revision 207753
1207753Smm/** 2207753Smm * \file lzma/filter.h 3207753Smm * \brief Common filter related types 4207753Smm */ 5207753Smm 6207753Smm/* 7207753Smm * Author: Lasse Collin 8207753Smm * 9207753Smm * This file has been put into the public domain. 10207753Smm * You can do whatever you want with this file. 11207753Smm * 12207753Smm * See ../lzma.h for information about liblzma as a whole. 13207753Smm */ 14207753Smm 15207753Smm#ifndef LZMA_H_INTERNAL 16207753Smm# error Never include this file directly. Use <lzma.h> instead. 17207753Smm#endif 18207753Smm 19207753Smm 20207753Smm/** 21207753Smm * \brief Maximum number of filters in a chain 22207753Smm * 23207753Smm * A filter chain can have 1-4 filters, of which three are allowed to change 24207753Smm * the size of the data. Usually only one or two filters are needed. 25207753Smm */ 26207753Smm#define LZMA_FILTERS_MAX 4 27207753Smm 28207753Smm 29207753Smm/** 30207753Smm * \brief Filter options 31207753Smm * 32207753Smm * This structure is used to pass Filter ID and a pointer filter's 33207753Smm * options to liblzma. A few functions work with a single lzma_filter 34207753Smm * structure, while most functions expect a filter chain. 35207753Smm * 36207753Smm * A filter chain is indicated with an array of lzma_filter structures. 37207753Smm * The array is terminated with .id = LZMA_VLI_UNKNOWN. Thus, the filter 38207753Smm * array must have LZMA_FILTERS_MAX + 1 elements (that is, five) to 39207753Smm * be able to hold any arbitrary filter chain. This is important when 40207753Smm * using lzma_block_header_decode() from block.h, because too small 41207753Smm * array would make liblzma write past the end of the filters array. 42207753Smm */ 43207753Smmtypedef struct { 44207753Smm /** 45207753Smm * \brief Filter ID 46207753Smm * 47207753Smm * Use constants whose name begin with `LZMA_FILTER_' to specify 48207753Smm * different filters. In an array of lzma_filter structures, use 49207753Smm * LZMA_VLI_UNKNOWN to indicate end of filters. 50207753Smm * 51207753Smm * \note This is not an enum, because on some systems enums 52207753Smm * cannot be 64-bit. 53207753Smm */ 54207753Smm lzma_vli id; 55207753Smm 56207753Smm /** 57207753Smm * \brief Pointer to filter-specific options structure 58207753Smm * 59207753Smm * If the filter doesn't need options, set this to NULL. If id is 60207753Smm * set to LZMA_VLI_UNKNOWN, options is ignored, and thus 61207753Smm * doesn't need be initialized. 62207753Smm * 63207753Smm * Some filters support changing the options in the middle of 64207753Smm * the encoding process. These filters store the pointer of the 65207753Smm * options structure and communicate with the application via 66207753Smm * modifications of the options structure. 67207753Smm */ 68207753Smm void *options; 69207753Smm 70207753Smm} lzma_filter; 71207753Smm 72207753Smm 73207753Smm/** 74207753Smm * \brief Test if the given Filter ID is supported for encoding 75207753Smm * 76207753Smm * Return true if the give Filter ID is supported for encoding by this 77207753Smm * liblzma build. Otherwise false is returned. 78207753Smm * 79207753Smm * There is no way to list which filters are available in this particular 80207753Smm * liblzma version and build. It would be useless, because the application 81207753Smm * couldn't know what kind of options the filter would need. 82207753Smm */ 83207753Smmextern LZMA_API(lzma_bool) lzma_filter_encoder_is_supported(lzma_vli id) 84207753Smm lzma_nothrow lzma_attr_const; 85207753Smm 86207753Smm 87207753Smm/** 88207753Smm * \brief Test if the given Filter ID is supported for decoding 89207753Smm * 90207753Smm * Return true if the give Filter ID is supported for decoding by this 91207753Smm * liblzma build. Otherwise false is returned. 92207753Smm */ 93207753Smmextern LZMA_API(lzma_bool) lzma_filter_decoder_is_supported(lzma_vli id) 94207753Smm lzma_nothrow lzma_attr_const; 95207753Smm 96207753Smm 97207753Smm/** 98207753Smm * \brief Copy the filters array 99207753Smm * 100207753Smm * Copy the Filter IDs and filter-specific options from src to dest. 101207753Smm * Up to LZMA_FILTERS_MAX filters are copied, plus the terminating 102207753Smm * .id == LZMA_VLI_UNKNOWN. Thus, dest should have at least 103207753Smm * LZMA_FILTERS_MAX + 1 elements space unless the caller knows that 104207753Smm * src is smaller than that. 105207753Smm * 106207753Smm * Unless the filter-specific options is NULL, the Filter ID has to be 107207753Smm * supported by liblzma, because liblzma needs to know the size of every 108207753Smm * filter-specific options structure. The filter-specific options are not 109207753Smm * validated. If options is NULL, any unsupported Filter IDs are copied 110207753Smm * without returning an error. 111207753Smm * 112207753Smm * Old filter-specific options in dest are not freed, so dest doesn't 113207753Smm * need to be initialized by the caller in any way. 114207753Smm * 115207753Smm * If an error occurs, memory possibly already allocated by this function 116207753Smm * is always freed. 117207753Smm * 118207753Smm * \return - LZMA_OK 119207753Smm * - LZMA_MEM_ERROR 120207753Smm * - LZMA_OPTIONS_ERROR: Unsupported Filter ID and its options 121207753Smm * is not NULL. 122207753Smm * - LZMA_PROG_ERROR: src or dest is NULL. 123207753Smm */ 124207753Smmextern LZMA_API(lzma_ret) lzma_filters_copy(const lzma_filter *src, 125207753Smm lzma_filter *dest, lzma_allocator *allocator) lzma_nothrow; 126207753Smm 127207753Smm 128207753Smm/** 129207753Smm * \brief Calculate rough memory requirements for raw encoder 130207753Smm * 131207753Smm * Because the calculation is rough, this function can be used to calculate 132207753Smm * the memory requirements for Block and Stream encoders too. 133207753Smm * 134207753Smm * \param filters Array of filters terminated with 135207753Smm * .id == LZMA_VLI_UNKNOWN. 136207753Smm * 137207753Smm * \return Rough number of bytes of memory required for the given 138207753Smm * filter chain when encoding. 139207753Smm */ 140207753Smmextern LZMA_API(uint64_t) lzma_raw_encoder_memusage(const lzma_filter *filters) 141207753Smm lzma_nothrow lzma_attr_pure; 142207753Smm 143207753Smm 144207753Smm/** 145207753Smm * \brief Calculate rough memory requirements for raw decoder 146207753Smm * 147207753Smm * Because the calculation is rough, this function can be used to calculate 148207753Smm * the memory requirements for Block and Stream decoders too. 149207753Smm * 150207753Smm * \param filters Array of filters terminated with 151207753Smm * .id == LZMA_VLI_UNKNOWN. 152207753Smm * 153207753Smm * \return Rough number of bytes of memory required for the given 154207753Smm * filter chain when decoding. 155207753Smm */ 156207753Smmextern LZMA_API(uint64_t) lzma_raw_decoder_memusage(const lzma_filter *filters) 157207753Smm lzma_nothrow lzma_attr_pure; 158207753Smm 159207753Smm 160207753Smm/** 161207753Smm * \brief Initialize raw encoder 162207753Smm * 163207753Smm * This function may be useful when implementing custom file formats. 164207753Smm * 165207753Smm * \param strm Pointer to properly prepared lzma_stream 166207753Smm * \param filters Array of lzma_filter structures. The end of the 167207753Smm * array must be marked with .id = LZMA_VLI_UNKNOWN. 168207753Smm * 169207753Smm * The `action' with lzma_code() can be LZMA_RUN, LZMA_SYNC_FLUSH (if the 170207753Smm * filter chain supports it), or LZMA_FINISH. 171207753Smm * 172207753Smm * \return - LZMA_OK 173207753Smm * - LZMA_MEM_ERROR 174207753Smm * - LZMA_OPTIONS_ERROR 175207753Smm * - LZMA_PROG_ERROR 176207753Smm */ 177207753Smmextern LZMA_API(lzma_ret) lzma_raw_encoder( 178207753Smm lzma_stream *strm, const lzma_filter *filters) 179207753Smm lzma_nothrow lzma_attr_warn_unused_result; 180207753Smm 181207753Smm 182207753Smm/** 183207753Smm * \brief Initialize raw decoder 184207753Smm * 185207753Smm * The initialization of raw decoder goes similarly to raw encoder. 186207753Smm * 187207753Smm * The `action' with lzma_code() can be LZMA_RUN or LZMA_FINISH. Using 188207753Smm * LZMA_FINISH is not required, it is supported just for convenience. 189207753Smm * 190207753Smm * \return - LZMA_OK 191207753Smm * - LZMA_MEM_ERROR 192207753Smm * - LZMA_OPTIONS_ERROR 193207753Smm * - LZMA_PROG_ERROR 194207753Smm */ 195207753Smmextern LZMA_API(lzma_ret) lzma_raw_decoder( 196207753Smm lzma_stream *strm, const lzma_filter *filters) 197207753Smm lzma_nothrow lzma_attr_warn_unused_result; 198207753Smm 199207753Smm 200207753Smm/** 201207753Smm * \brief Update the filter chain in the encoder 202207753Smm * 203207753Smm * This function is for advanced users only. This function has two slightly 204207753Smm * different purposes: 205207753Smm * 206207753Smm * - After LZMA_FULL_FLUSH when using Stream encoder: Set a new filter 207207753Smm * chain, which will be used starting from the next Block. 208207753Smm * 209207753Smm * - After LZMA_SYNC_FLUSH using Raw, Block, or Stream encoder: Change 210207753Smm * the filter-specific options in the middle of encoding. The actual 211207753Smm * filters in the chain (Filter IDs) cannot be changed. In the future, 212207753Smm * it might become possible to change the filter options without 213207753Smm * using LZMA_SYNC_FLUSH. 214207753Smm * 215207753Smm * While rarely useful, this function may be called also when no data has 216207753Smm * been compressed yet. In that case, this function will behave as if 217207753Smm * LZMA_FULL_FLUSH (Stream encoder) or LZMA_SYNC_FLUSH (Raw or Block 218207753Smm * encoder) had been used right before calling this function. 219207753Smm * 220207753Smm * \return - LZMA_OK 221207753Smm * - LZMA_MEM_ERROR 222207753Smm * - LZMA_MEMLIMIT_ERROR 223207753Smm * - LZMA_OPTIONS_ERROR 224207753Smm * - LZMA_PROG_ERROR 225207753Smm */ 226207753Smmextern LZMA_API(lzma_ret) lzma_filters_update( 227207753Smm lzma_stream *strm, const lzma_filter *filters) lzma_nothrow; 228207753Smm 229207753Smm 230207753Smm/** 231207753Smm * \brief Single-call raw encoder 232207753Smm * 233207753Smm * \param filters Array of lzma_filter structures. The end of the 234207753Smm * array must be marked with .id = LZMA_VLI_UNKNOWN. 235207753Smm * \param allocator lzma_allocator for custom allocator functions. 236207753Smm * Set to NULL to use malloc() and free(). 237207753Smm * \param in Beginning of the input buffer 238207753Smm * \param in_size Size of the input buffer 239207753Smm * \param out Beginning of the output buffer 240207753Smm * \param out_pos The next byte will be written to out[*out_pos]. 241207753Smm * *out_pos is updated only if encoding succeeds. 242207753Smm * \param out_size Size of the out buffer; the first byte into 243207753Smm * which no data is written to is out[out_size]. 244207753Smm * 245207753Smm * \return - LZMA_OK: Encoding was successful. 246207753Smm * - LZMA_BUF_ERROR: Not enough output buffer space. 247207753Smm * - LZMA_OPTIONS_ERROR 248207753Smm * - LZMA_MEM_ERROR 249207753Smm * - LZMA_DATA_ERROR 250207753Smm * - LZMA_PROG_ERROR 251207753Smm * 252207753Smm * \note There is no function to calculate how big output buffer 253207753Smm * would surely be big enough. (lzma_stream_buffer_bound() 254207753Smm * works only for lzma_stream_buffer_encode().) 255207753Smm */ 256207753Smmextern LZMA_API(lzma_ret) lzma_raw_buffer_encode( 257207753Smm const lzma_filter *filters, lzma_allocator *allocator, 258207753Smm const uint8_t *in, size_t in_size, uint8_t *out, 259207753Smm size_t *out_pos, size_t out_size) lzma_nothrow; 260207753Smm 261207753Smm 262207753Smm/** 263207753Smm * \brief Single-call raw decoder 264207753Smm * 265207753Smm * \param filters Array of lzma_filter structures. The end of the 266207753Smm * array must be marked with .id = LZMA_VLI_UNKNOWN. 267207753Smm * \param allocator lzma_allocator for custom allocator functions. 268207753Smm * Set to NULL to use malloc() and free(). 269207753Smm * \param in Beginning of the input buffer 270207753Smm * \param in_pos The next byte will be read from in[*in_pos]. 271207753Smm * *in_pos is updated only if decoding succeeds. 272207753Smm * \param in_size Size of the input buffer; the first byte that 273207753Smm * won't be read is in[in_size]. 274207753Smm * \param out Beginning of the output buffer 275207753Smm * \param out_pos The next byte will be written to out[*out_pos]. 276207753Smm * *out_pos is updated only if encoding succeeds. 277207753Smm * \param out_size Size of the out buffer; the first byte into 278207753Smm * which no data is written to is out[out_size]. 279207753Smm */ 280207753Smmextern LZMA_API(lzma_ret) lzma_raw_buffer_decode( 281207753Smm const lzma_filter *filters, lzma_allocator *allocator, 282207753Smm const uint8_t *in, size_t *in_pos, size_t in_size, 283207753Smm uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow; 284207753Smm 285207753Smm 286207753Smm/** 287207753Smm * \brief Get the size of the Filter Properties field 288207753Smm * 289207753Smm * This function may be useful when implementing custom file formats 290207753Smm * using the raw encoder and decoder. 291207753Smm * 292207753Smm * \param size Pointer to uint32_t to hold the size of the properties 293207753Smm * \param filter Filter ID and options (the size of the properties may 294207753Smm * vary depending on the options) 295207753Smm * 296207753Smm * \return - LZMA_OK 297207753Smm * - LZMA_OPTIONS_ERROR 298207753Smm * - LZMA_PROG_ERROR 299207753Smm * 300207753Smm * \note This function validates the Filter ID, but does not 301207753Smm * necessarily validate the options. Thus, it is possible 302207753Smm * that this returns LZMA_OK while the following call to 303207753Smm * lzma_properties_encode() returns LZMA_OPTIONS_ERROR. 304207753Smm */ 305207753Smmextern LZMA_API(lzma_ret) lzma_properties_size( 306207753Smm uint32_t *size, const lzma_filter *filter) lzma_nothrow; 307207753Smm 308207753Smm 309207753Smm/** 310207753Smm * \brief Encode the Filter Properties field 311207753Smm * 312207753Smm * \param filter Filter ID and options 313207753Smm * \param props Buffer to hold the encoded options. The size of 314207753Smm * buffer must have been already determined with 315207753Smm * lzma_properties_size(). 316207753Smm * 317207753Smm * \return - LZMA_OK 318207753Smm * - LZMA_OPTIONS_ERROR 319207753Smm * - LZMA_PROG_ERROR 320207753Smm * 321207753Smm * \note Even this function won't validate more options than actually 322207753Smm * necessary. Thus, it is possible that encoding the properties 323207753Smm * succeeds but using the same options to initialize the encoder 324207753Smm * will fail. 325207753Smm * 326207753Smm * \note It is OK to skip calling this function if 327207753Smm * lzma_properties_size() indicated that the size 328207753Smm * of the Filter Properties field is zero. 329207753Smm */ 330207753Smmextern LZMA_API(lzma_ret) lzma_properties_encode( 331207753Smm const lzma_filter *filter, uint8_t *props) lzma_nothrow; 332207753Smm 333207753Smm 334207753Smm/** 335207753Smm * \brief Decode the Filter Properties field 336207753Smm * 337207753Smm * \param filter filter->id must have been set to the correct 338207753Smm * Filter ID. filter->options doesn't need to be 339207753Smm * initialized (it's not freed by this function). The 340207753Smm * decoded options will be stored to filter->options. 341207753Smm * filter->options is set to NULL if there are no 342207753Smm * properties or if an error occurs. 343207753Smm * \param allocator Custom memory allocator used to allocate the 344207753Smm * options. Set to NULL to use the default malloc(), 345207753Smm * and in case of an error, also free(). 346207753Smm * \param props Input buffer containing the properties. 347207753Smm * \param props_size Size of the properties. This must be the exact 348207753Smm * size; giving too much or too little input will 349207753Smm * return LZMA_OPTIONS_ERROR. 350207753Smm * 351207753Smm * \return - LZMA_OK 352207753Smm * - LZMA_OPTIONS_ERROR 353207753Smm * - LZMA_MEM_ERROR 354207753Smm */ 355207753Smmextern LZMA_API(lzma_ret) lzma_properties_decode( 356207753Smm lzma_filter *filter, lzma_allocator *allocator, 357207753Smm const uint8_t *props, size_t props_size) lzma_nothrow; 358207753Smm 359207753Smm 360207753Smm/** 361207753Smm * \brief Calculate encoded size of a Filter Flags field 362207753Smm * 363207753Smm * Knowing the size of Filter Flags is useful to know when allocating 364207753Smm * memory to hold the encoded Filter Flags. 365207753Smm * 366207753Smm * \param size Pointer to integer to hold the calculated size 367207753Smm * \param filters Filter ID and associated options whose encoded 368207753Smm * size is to be calculated 369207753Smm * 370207753Smm * \return - LZMA_OK: *size set successfully. Note that this doesn't 371207753Smm * guarantee that filters->options is valid, thus 372207753Smm * lzma_filter_flags_encode() may still fail. 373207753Smm * - LZMA_OPTIONS_ERROR: Unknown Filter ID or unsupported options. 374207753Smm * - LZMA_PROG_ERROR: Invalid options 375207753Smm * 376207753Smm * \note If you need to calculate size of List of Filter Flags, 377207753Smm * you need to loop over every lzma_filter entry. 378207753Smm */ 379207753Smmextern LZMA_API(lzma_ret) lzma_filter_flags_size( 380207753Smm uint32_t *size, const lzma_filter *filters) 381207753Smm lzma_nothrow lzma_attr_warn_unused_result; 382207753Smm 383207753Smm 384207753Smm/** 385207753Smm * \brief Encode Filter Flags into given buffer 386207753Smm * 387207753Smm * In contrast to some functions, this doesn't allocate the needed buffer. 388207753Smm * This is due to how this function is used internally by liblzma. 389207753Smm * 390207753Smm * \param filters Filter ID and options to be encoded 391207753Smm * \param out Beginning of the output buffer 392207753Smm * \param out_pos out[*out_pos] is the next write position. This 393207753Smm * is updated by the encoder. 394207753Smm * \param out_size out[out_size] is the first byte to not write. 395207753Smm * 396207753Smm * \return - LZMA_OK: Encoding was successful. 397207753Smm * - LZMA_OPTIONS_ERROR: Invalid or unsupported options. 398207753Smm * - LZMA_PROG_ERROR: Invalid options or not enough output 399207753Smm * buffer space (you should have checked it with 400207753Smm * lzma_filter_flags_size()). 401207753Smm */ 402207753Smmextern LZMA_API(lzma_ret) lzma_filter_flags_encode(const lzma_filter *filters, 403207753Smm uint8_t *out, size_t *out_pos, size_t out_size) 404207753Smm lzma_nothrow lzma_attr_warn_unused_result; 405207753Smm 406207753Smm 407207753Smm/** 408207753Smm * \brief Decode Filter Flags from given buffer 409207753Smm * 410207753Smm * The decoded result is stored into *filters. filters->options is 411207753Smm * initialized but the old value is NOT free()d. 412207753Smm * 413207753Smm * \return - LZMA_OK 414207753Smm * - LZMA_OPTIONS_ERROR 415207753Smm * - LZMA_MEM_ERROR 416207753Smm * - LZMA_PROG_ERROR 417207753Smm */ 418207753Smmextern LZMA_API(lzma_ret) lzma_filter_flags_decode( 419207753Smm lzma_filter *filters, lzma_allocator *allocator, 420207753Smm const uint8_t *in, size_t *in_pos, size_t in_size) 421207753Smm lzma_nothrow lzma_attr_warn_unused_result; 422