filter.h revision 215187
1207753Smm/** 2207753Smm * \file lzma/filter.h 3215187Smm * \brief Common filter related types and functions 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 void *options; 64207753Smm 65207753Smm} lzma_filter; 66207753Smm 67207753Smm 68207753Smm/** 69207753Smm * \brief Test if the given Filter ID is supported for encoding 70207753Smm * 71207753Smm * Return true if the give Filter ID is supported for encoding by this 72207753Smm * liblzma build. Otherwise false is returned. 73207753Smm * 74207753Smm * There is no way to list which filters are available in this particular 75207753Smm * liblzma version and build. It would be useless, because the application 76207753Smm * couldn't know what kind of options the filter would need. 77207753Smm */ 78207753Smmextern LZMA_API(lzma_bool) lzma_filter_encoder_is_supported(lzma_vli id) 79207753Smm lzma_nothrow lzma_attr_const; 80207753Smm 81207753Smm 82207753Smm/** 83207753Smm * \brief Test if the given Filter ID is supported for decoding 84207753Smm * 85207753Smm * Return true if the give Filter ID is supported for decoding by this 86207753Smm * liblzma build. Otherwise false is returned. 87207753Smm */ 88207753Smmextern LZMA_API(lzma_bool) lzma_filter_decoder_is_supported(lzma_vli id) 89207753Smm lzma_nothrow lzma_attr_const; 90207753Smm 91207753Smm 92207753Smm/** 93207753Smm * \brief Copy the filters array 94207753Smm * 95207753Smm * Copy the Filter IDs and filter-specific options from src to dest. 96207753Smm * Up to LZMA_FILTERS_MAX filters are copied, plus the terminating 97207753Smm * .id == LZMA_VLI_UNKNOWN. Thus, dest should have at least 98207753Smm * LZMA_FILTERS_MAX + 1 elements space unless the caller knows that 99207753Smm * src is smaller than that. 100207753Smm * 101207753Smm * Unless the filter-specific options is NULL, the Filter ID has to be 102207753Smm * supported by liblzma, because liblzma needs to know the size of every 103207753Smm * filter-specific options structure. The filter-specific options are not 104207753Smm * validated. If options is NULL, any unsupported Filter IDs are copied 105207753Smm * without returning an error. 106207753Smm * 107207753Smm * Old filter-specific options in dest are not freed, so dest doesn't 108207753Smm * need to be initialized by the caller in any way. 109207753Smm * 110207753Smm * If an error occurs, memory possibly already allocated by this function 111207753Smm * is always freed. 112207753Smm * 113207753Smm * \return - LZMA_OK 114207753Smm * - LZMA_MEM_ERROR 115207753Smm * - LZMA_OPTIONS_ERROR: Unsupported Filter ID and its options 116207753Smm * is not NULL. 117207753Smm * - LZMA_PROG_ERROR: src or dest is NULL. 118207753Smm */ 119207753Smmextern LZMA_API(lzma_ret) lzma_filters_copy(const lzma_filter *src, 120207753Smm lzma_filter *dest, lzma_allocator *allocator) lzma_nothrow; 121207753Smm 122207753Smm 123207753Smm/** 124215187Smm * \brief Calculate approximate memory requirements for raw encoder 125207753Smm * 126215187Smm * This function can be used to calculate the memory requirements for 127215187Smm * Block and Stream encoders too because Block and Stream encoders don't 128215187Smm * need significantly more memory than raw encoder. 129207753Smm * 130207753Smm * \param filters Array of filters terminated with 131207753Smm * .id == LZMA_VLI_UNKNOWN. 132207753Smm * 133215187Smm * \return Number of bytes of memory required for the given 134207753Smm * filter chain when encoding. 135207753Smm */ 136207753Smmextern LZMA_API(uint64_t) lzma_raw_encoder_memusage(const lzma_filter *filters) 137207753Smm lzma_nothrow lzma_attr_pure; 138207753Smm 139207753Smm 140207753Smm/** 141215187Smm * \brief Calculate approximate memory requirements for raw decoder 142207753Smm * 143215187Smm * This function can be used to calculate the memory requirements for 144215187Smm * Block and Stream decoders too because Block and Stream decoders don't 145215187Smm * need significantly more memory than raw decoder. 146207753Smm * 147207753Smm * \param filters Array of filters terminated with 148207753Smm * .id == LZMA_VLI_UNKNOWN. 149207753Smm * 150215187Smm * \return Number of bytes of memory required for the given 151207753Smm * filter chain when decoding. 152207753Smm */ 153207753Smmextern LZMA_API(uint64_t) lzma_raw_decoder_memusage(const lzma_filter *filters) 154207753Smm lzma_nothrow lzma_attr_pure; 155207753Smm 156207753Smm 157207753Smm/** 158207753Smm * \brief Initialize raw encoder 159207753Smm * 160207753Smm * This function may be useful when implementing custom file formats. 161207753Smm * 162207753Smm * \param strm Pointer to properly prepared lzma_stream 163207753Smm * \param filters Array of lzma_filter structures. The end of the 164207753Smm * array must be marked with .id = LZMA_VLI_UNKNOWN. 165207753Smm * 166207753Smm * The `action' with lzma_code() can be LZMA_RUN, LZMA_SYNC_FLUSH (if the 167207753Smm * filter chain supports it), or LZMA_FINISH. 168207753Smm * 169207753Smm * \return - LZMA_OK 170207753Smm * - LZMA_MEM_ERROR 171207753Smm * - LZMA_OPTIONS_ERROR 172207753Smm * - LZMA_PROG_ERROR 173207753Smm */ 174207753Smmextern LZMA_API(lzma_ret) lzma_raw_encoder( 175207753Smm lzma_stream *strm, const lzma_filter *filters) 176207753Smm lzma_nothrow lzma_attr_warn_unused_result; 177207753Smm 178207753Smm 179207753Smm/** 180207753Smm * \brief Initialize raw decoder 181207753Smm * 182207753Smm * The initialization of raw decoder goes similarly to raw encoder. 183207753Smm * 184207753Smm * The `action' with lzma_code() can be LZMA_RUN or LZMA_FINISH. Using 185207753Smm * LZMA_FINISH is not required, it is supported just for convenience. 186207753Smm * 187207753Smm * \return - LZMA_OK 188207753Smm * - LZMA_MEM_ERROR 189207753Smm * - LZMA_OPTIONS_ERROR 190207753Smm * - LZMA_PROG_ERROR 191207753Smm */ 192207753Smmextern LZMA_API(lzma_ret) lzma_raw_decoder( 193207753Smm lzma_stream *strm, const lzma_filter *filters) 194207753Smm lzma_nothrow lzma_attr_warn_unused_result; 195207753Smm 196207753Smm 197207753Smm/** 198207753Smm * \brief Update the filter chain in the encoder 199207753Smm * 200207753Smm * This function is for advanced users only. This function has two slightly 201207753Smm * different purposes: 202207753Smm * 203207753Smm * - After LZMA_FULL_FLUSH when using Stream encoder: Set a new filter 204207753Smm * chain, which will be used starting from the next Block. 205207753Smm * 206207753Smm * - After LZMA_SYNC_FLUSH using Raw, Block, or Stream encoder: Change 207207753Smm * the filter-specific options in the middle of encoding. The actual 208207753Smm * filters in the chain (Filter IDs) cannot be changed. In the future, 209207753Smm * it might become possible to change the filter options without 210207753Smm * using LZMA_SYNC_FLUSH. 211207753Smm * 212207753Smm * While rarely useful, this function may be called also when no data has 213207753Smm * been compressed yet. In that case, this function will behave as if 214207753Smm * LZMA_FULL_FLUSH (Stream encoder) or LZMA_SYNC_FLUSH (Raw or Block 215207753Smm * encoder) had been used right before calling this function. 216207753Smm * 217207753Smm * \return - LZMA_OK 218207753Smm * - LZMA_MEM_ERROR 219207753Smm * - LZMA_MEMLIMIT_ERROR 220207753Smm * - LZMA_OPTIONS_ERROR 221207753Smm * - LZMA_PROG_ERROR 222207753Smm */ 223207753Smmextern LZMA_API(lzma_ret) lzma_filters_update( 224207753Smm lzma_stream *strm, const lzma_filter *filters) lzma_nothrow; 225207753Smm 226207753Smm 227207753Smm/** 228207753Smm * \brief Single-call raw encoder 229207753Smm * 230207753Smm * \param filters Array of lzma_filter structures. The end of the 231207753Smm * array must be marked with .id = LZMA_VLI_UNKNOWN. 232207753Smm * \param allocator lzma_allocator for custom allocator functions. 233207753Smm * Set to NULL to use malloc() and free(). 234207753Smm * \param in Beginning of the input buffer 235207753Smm * \param in_size Size of the input buffer 236207753Smm * \param out Beginning of the output buffer 237207753Smm * \param out_pos The next byte will be written to out[*out_pos]. 238207753Smm * *out_pos is updated only if encoding succeeds. 239207753Smm * \param out_size Size of the out buffer; the first byte into 240207753Smm * which no data is written to is out[out_size]. 241207753Smm * 242207753Smm * \return - LZMA_OK: Encoding was successful. 243207753Smm * - LZMA_BUF_ERROR: Not enough output buffer space. 244207753Smm * - LZMA_OPTIONS_ERROR 245207753Smm * - LZMA_MEM_ERROR 246207753Smm * - LZMA_DATA_ERROR 247207753Smm * - LZMA_PROG_ERROR 248207753Smm * 249207753Smm * \note There is no function to calculate how big output buffer 250207753Smm * would surely be big enough. (lzma_stream_buffer_bound() 251215187Smm * works only for lzma_stream_buffer_encode(); raw encoder 252215187Smm * won't necessarily meet that bound.) 253207753Smm */ 254207753Smmextern LZMA_API(lzma_ret) lzma_raw_buffer_encode( 255207753Smm const lzma_filter *filters, lzma_allocator *allocator, 256207753Smm const uint8_t *in, size_t in_size, uint8_t *out, 257207753Smm size_t *out_pos, size_t out_size) lzma_nothrow; 258207753Smm 259207753Smm 260207753Smm/** 261207753Smm * \brief Single-call raw decoder 262207753Smm * 263207753Smm * \param filters Array of lzma_filter structures. The end of the 264207753Smm * array must be marked with .id = LZMA_VLI_UNKNOWN. 265207753Smm * \param allocator lzma_allocator for custom allocator functions. 266207753Smm * Set to NULL to use malloc() and free(). 267207753Smm * \param in Beginning of the input buffer 268207753Smm * \param in_pos The next byte will be read from in[*in_pos]. 269207753Smm * *in_pos is updated only if decoding succeeds. 270207753Smm * \param in_size Size of the input buffer; the first byte that 271207753Smm * won't be read is in[in_size]. 272207753Smm * \param out Beginning of the output buffer 273207753Smm * \param out_pos The next byte will be written to out[*out_pos]. 274207753Smm * *out_pos is updated only if encoding succeeds. 275207753Smm * \param out_size Size of the out buffer; the first byte into 276207753Smm * which no data is written to is out[out_size]. 277207753Smm */ 278207753Smmextern LZMA_API(lzma_ret) lzma_raw_buffer_decode( 279207753Smm const lzma_filter *filters, lzma_allocator *allocator, 280207753Smm const uint8_t *in, size_t *in_pos, size_t in_size, 281207753Smm uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow; 282207753Smm 283207753Smm 284207753Smm/** 285207753Smm * \brief Get the size of the Filter Properties field 286207753Smm * 287207753Smm * This function may be useful when implementing custom file formats 288207753Smm * using the raw encoder and decoder. 289207753Smm * 290207753Smm * \param size Pointer to uint32_t to hold the size of the properties 291207753Smm * \param filter Filter ID and options (the size of the properties may 292207753Smm * vary depending on the options) 293207753Smm * 294207753Smm * \return - LZMA_OK 295207753Smm * - LZMA_OPTIONS_ERROR 296207753Smm * - LZMA_PROG_ERROR 297207753Smm * 298207753Smm * \note This function validates the Filter ID, but does not 299207753Smm * necessarily validate the options. Thus, it is possible 300207753Smm * that this returns LZMA_OK while the following call to 301207753Smm * lzma_properties_encode() returns LZMA_OPTIONS_ERROR. 302207753Smm */ 303207753Smmextern LZMA_API(lzma_ret) lzma_properties_size( 304207753Smm uint32_t *size, const lzma_filter *filter) lzma_nothrow; 305207753Smm 306207753Smm 307207753Smm/** 308207753Smm * \brief Encode the Filter Properties field 309207753Smm * 310207753Smm * \param filter Filter ID and options 311207753Smm * \param props Buffer to hold the encoded options. The size of 312207753Smm * buffer must have been already determined with 313207753Smm * lzma_properties_size(). 314207753Smm * 315207753Smm * \return - LZMA_OK 316207753Smm * - LZMA_OPTIONS_ERROR 317207753Smm * - LZMA_PROG_ERROR 318207753Smm * 319207753Smm * \note Even this function won't validate more options than actually 320207753Smm * necessary. Thus, it is possible that encoding the properties 321207753Smm * succeeds but using the same options to initialize the encoder 322207753Smm * will fail. 323207753Smm * 324215187Smm * \note If lzma_properties_size() indicated that the size 325215187Smm * of the Filter Properties field is zero, calling 326215187Smm * lzma_properties_encode() is not required, but it 327215187Smm * won't do any harm either. 328207753Smm */ 329207753Smmextern LZMA_API(lzma_ret) lzma_properties_encode( 330207753Smm const lzma_filter *filter, uint8_t *props) lzma_nothrow; 331207753Smm 332207753Smm 333207753Smm/** 334207753Smm * \brief Decode the Filter Properties field 335207753Smm * 336207753Smm * \param filter filter->id must have been set to the correct 337207753Smm * Filter ID. filter->options doesn't need to be 338207753Smm * initialized (it's not freed by this function). The 339207753Smm * decoded options will be stored to filter->options. 340207753Smm * filter->options is set to NULL if there are no 341207753Smm * properties or if an error occurs. 342207753Smm * \param allocator Custom memory allocator used to allocate the 343207753Smm * options. Set to NULL to use the default malloc(), 344207753Smm * and in case of an error, also free(). 345207753Smm * \param props Input buffer containing the properties. 346207753Smm * \param props_size Size of the properties. This must be the exact 347207753Smm * size; giving too much or too little input will 348207753Smm * return LZMA_OPTIONS_ERROR. 349207753Smm * 350207753Smm * \return - LZMA_OK 351207753Smm * - LZMA_OPTIONS_ERROR 352207753Smm * - LZMA_MEM_ERROR 353207753Smm */ 354207753Smmextern LZMA_API(lzma_ret) lzma_properties_decode( 355207753Smm lzma_filter *filter, lzma_allocator *allocator, 356207753Smm const uint8_t *props, size_t props_size) lzma_nothrow; 357207753Smm 358207753Smm 359207753Smm/** 360207753Smm * \brief Calculate encoded size of a Filter Flags field 361207753Smm * 362207753Smm * Knowing the size of Filter Flags is useful to know when allocating 363207753Smm * memory to hold the encoded Filter Flags. 364207753Smm * 365207753Smm * \param size Pointer to integer to hold the calculated size 366215187Smm * \param filter Filter ID and associated options whose encoded 367207753Smm * size is to be calculated 368207753Smm * 369207753Smm * \return - LZMA_OK: *size set successfully. Note that this doesn't 370215187Smm * guarantee that filter->options is valid, thus 371207753Smm * lzma_filter_flags_encode() may still fail. 372207753Smm * - LZMA_OPTIONS_ERROR: Unknown Filter ID or unsupported options. 373207753Smm * - LZMA_PROG_ERROR: Invalid options 374207753Smm * 375207753Smm * \note If you need to calculate size of List of Filter Flags, 376207753Smm * you need to loop over every lzma_filter entry. 377207753Smm */ 378207753Smmextern LZMA_API(lzma_ret) lzma_filter_flags_size( 379215187Smm uint32_t *size, const lzma_filter *filter) 380207753Smm lzma_nothrow lzma_attr_warn_unused_result; 381207753Smm 382207753Smm 383207753Smm/** 384207753Smm * \brief Encode Filter Flags into given buffer 385207753Smm * 386207753Smm * In contrast to some functions, this doesn't allocate the needed buffer. 387207753Smm * This is due to how this function is used internally by liblzma. 388207753Smm * 389215187Smm * \param filter Filter ID and options to be encoded 390207753Smm * \param out Beginning of the output buffer 391207753Smm * \param out_pos out[*out_pos] is the next write position. This 392207753Smm * is updated by the encoder. 393207753Smm * \param out_size out[out_size] is the first byte to not write. 394207753Smm * 395207753Smm * \return - LZMA_OK: Encoding was successful. 396207753Smm * - LZMA_OPTIONS_ERROR: Invalid or unsupported options. 397207753Smm * - LZMA_PROG_ERROR: Invalid options or not enough output 398207753Smm * buffer space (you should have checked it with 399207753Smm * lzma_filter_flags_size()). 400207753Smm */ 401215187Smmextern LZMA_API(lzma_ret) lzma_filter_flags_encode(const lzma_filter *filter, 402207753Smm uint8_t *out, size_t *out_pos, size_t out_size) 403207753Smm lzma_nothrow lzma_attr_warn_unused_result; 404207753Smm 405207753Smm 406207753Smm/** 407207753Smm * \brief Decode Filter Flags from given buffer 408207753Smm * 409215187Smm * The decoded result is stored into *filter. The old value of 410215187Smm * filter->options is not free()d. 411207753Smm * 412207753Smm * \return - LZMA_OK 413207753Smm * - LZMA_OPTIONS_ERROR 414207753Smm * - LZMA_MEM_ERROR 415207753Smm * - LZMA_PROG_ERROR 416207753Smm */ 417207753Smmextern LZMA_API(lzma_ret) lzma_filter_flags_decode( 418215187Smm lzma_filter *filter, lzma_allocator *allocator, 419207753Smm const uint8_t *in, size_t *in_pos, size_t in_size) 420207753Smm lzma_nothrow lzma_attr_warn_unused_result; 421