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 */ 119292588Sdelphijextern LZMA_API(lzma_ret) lzma_filters_copy( 120292588Sdelphij const lzma_filter *src, lzma_filter *dest, 121292588Sdelphij const lzma_allocator *allocator) lzma_nothrow; 122207753Smm 123207753Smm 124207753Smm/** 125215187Smm * \brief Calculate approximate memory requirements for raw encoder 126207753Smm * 127215187Smm * This function can be used to calculate the memory requirements for 128215187Smm * Block and Stream encoders too because Block and Stream encoders don't 129215187Smm * need significantly more memory than raw encoder. 130207753Smm * 131207753Smm * \param filters Array of filters terminated with 132207753Smm * .id == LZMA_VLI_UNKNOWN. 133207753Smm * 134215187Smm * \return Number of bytes of memory required for the given 135223935Smm * filter chain when encoding. If an error occurs, 136223935Smm * for example due to unsupported filter chain, 137223935Smm * UINT64_MAX is returned. 138207753Smm */ 139207753Smmextern LZMA_API(uint64_t) lzma_raw_encoder_memusage(const lzma_filter *filters) 140207753Smm lzma_nothrow lzma_attr_pure; 141207753Smm 142207753Smm 143207753Smm/** 144215187Smm * \brief Calculate approximate memory requirements for raw decoder 145207753Smm * 146215187Smm * This function can be used to calculate the memory requirements for 147215187Smm * Block and Stream decoders too because Block and Stream decoders don't 148215187Smm * need significantly more memory than raw decoder. 149207753Smm * 150207753Smm * \param filters Array of filters terminated with 151207753Smm * .id == LZMA_VLI_UNKNOWN. 152207753Smm * 153215187Smm * \return Number of bytes of memory required for the given 154223935Smm * filter chain when decoding. If an error occurs, 155223935Smm * for example due to unsupported filter chain, 156223935Smm * UINT64_MAX is returned. 157207753Smm */ 158207753Smmextern LZMA_API(uint64_t) lzma_raw_decoder_memusage(const lzma_filter *filters) 159207753Smm lzma_nothrow lzma_attr_pure; 160207753Smm 161207753Smm 162207753Smm/** 163207753Smm * \brief Initialize raw encoder 164207753Smm * 165207753Smm * This function may be useful when implementing custom file formats. 166207753Smm * 167207753Smm * \param strm Pointer to properly prepared lzma_stream 168207753Smm * \param filters Array of lzma_filter structures. The end of the 169207753Smm * array must be marked with .id = LZMA_VLI_UNKNOWN. 170207753Smm * 171207753Smm * The `action' with lzma_code() can be LZMA_RUN, LZMA_SYNC_FLUSH (if the 172207753Smm * filter chain supports it), or LZMA_FINISH. 173207753Smm * 174207753Smm * \return - LZMA_OK 175207753Smm * - LZMA_MEM_ERROR 176207753Smm * - LZMA_OPTIONS_ERROR 177207753Smm * - LZMA_PROG_ERROR 178207753Smm */ 179207753Smmextern LZMA_API(lzma_ret) lzma_raw_encoder( 180207753Smm lzma_stream *strm, const lzma_filter *filters) 181207753Smm lzma_nothrow lzma_attr_warn_unused_result; 182207753Smm 183207753Smm 184207753Smm/** 185207753Smm * \brief Initialize raw decoder 186207753Smm * 187207753Smm * The initialization of raw decoder goes similarly to raw encoder. 188207753Smm * 189207753Smm * The `action' with lzma_code() can be LZMA_RUN or LZMA_FINISH. Using 190207753Smm * LZMA_FINISH is not required, it is supported just for convenience. 191207753Smm * 192207753Smm * \return - LZMA_OK 193207753Smm * - LZMA_MEM_ERROR 194207753Smm * - LZMA_OPTIONS_ERROR 195207753Smm * - LZMA_PROG_ERROR 196207753Smm */ 197207753Smmextern LZMA_API(lzma_ret) lzma_raw_decoder( 198207753Smm lzma_stream *strm, const lzma_filter *filters) 199207753Smm lzma_nothrow lzma_attr_warn_unused_result; 200207753Smm 201207753Smm 202207753Smm/** 203207753Smm * \brief Update the filter chain in the encoder 204207753Smm * 205207753Smm * This function is for advanced users only. This function has two slightly 206207753Smm * different purposes: 207207753Smm * 208207753Smm * - After LZMA_FULL_FLUSH when using Stream encoder: Set a new filter 209207753Smm * chain, which will be used starting from the next Block. 210207753Smm * 211207753Smm * - After LZMA_SYNC_FLUSH using Raw, Block, or Stream encoder: Change 212207753Smm * the filter-specific options in the middle of encoding. The actual 213207753Smm * filters in the chain (Filter IDs) cannot be changed. In the future, 214207753Smm * it might become possible to change the filter options without 215207753Smm * using LZMA_SYNC_FLUSH. 216207753Smm * 217207753Smm * While rarely useful, this function may be called also when no data has 218207753Smm * been compressed yet. In that case, this function will behave as if 219207753Smm * LZMA_FULL_FLUSH (Stream encoder) or LZMA_SYNC_FLUSH (Raw or Block 220207753Smm * encoder) had been used right before calling this function. 221207753Smm * 222207753Smm * \return - LZMA_OK 223207753Smm * - LZMA_MEM_ERROR 224207753Smm * - LZMA_MEMLIMIT_ERROR 225207753Smm * - LZMA_OPTIONS_ERROR 226207753Smm * - LZMA_PROG_ERROR 227207753Smm */ 228207753Smmextern LZMA_API(lzma_ret) lzma_filters_update( 229207753Smm lzma_stream *strm, const lzma_filter *filters) lzma_nothrow; 230207753Smm 231207753Smm 232207753Smm/** 233207753Smm * \brief Single-call raw encoder 234207753Smm * 235207753Smm * \param filters Array of lzma_filter structures. The end of the 236207753Smm * array must be marked with .id = LZMA_VLI_UNKNOWN. 237207753Smm * \param allocator lzma_allocator for custom allocator functions. 238207753Smm * Set to NULL to use malloc() and free(). 239207753Smm * \param in Beginning of the input buffer 240207753Smm * \param in_size Size of the input buffer 241207753Smm * \param out Beginning of the output buffer 242207753Smm * \param out_pos The next byte will be written to out[*out_pos]. 243207753Smm * *out_pos is updated only if encoding succeeds. 244207753Smm * \param out_size Size of the out buffer; the first byte into 245207753Smm * which no data is written to is out[out_size]. 246207753Smm * 247207753Smm * \return - LZMA_OK: Encoding was successful. 248207753Smm * - LZMA_BUF_ERROR: Not enough output buffer space. 249207753Smm * - LZMA_OPTIONS_ERROR 250207753Smm * - LZMA_MEM_ERROR 251207753Smm * - LZMA_DATA_ERROR 252207753Smm * - LZMA_PROG_ERROR 253207753Smm * 254207753Smm * \note There is no function to calculate how big output buffer 255207753Smm * would surely be big enough. (lzma_stream_buffer_bound() 256215187Smm * works only for lzma_stream_buffer_encode(); raw encoder 257215187Smm * won't necessarily meet that bound.) 258207753Smm */ 259207753Smmextern LZMA_API(lzma_ret) lzma_raw_buffer_encode( 260292588Sdelphij const lzma_filter *filters, const lzma_allocator *allocator, 261207753Smm const uint8_t *in, size_t in_size, uint8_t *out, 262207753Smm size_t *out_pos, size_t out_size) lzma_nothrow; 263207753Smm 264207753Smm 265207753Smm/** 266207753Smm * \brief Single-call raw decoder 267207753Smm * 268207753Smm * \param filters Array of lzma_filter structures. The end of the 269207753Smm * array must be marked with .id = LZMA_VLI_UNKNOWN. 270207753Smm * \param allocator lzma_allocator for custom allocator functions. 271207753Smm * Set to NULL to use malloc() and free(). 272207753Smm * \param in Beginning of the input buffer 273207753Smm * \param in_pos The next byte will be read from in[*in_pos]. 274207753Smm * *in_pos is updated only if decoding succeeds. 275207753Smm * \param in_size Size of the input buffer; the first byte that 276207753Smm * won't be read is in[in_size]. 277207753Smm * \param out Beginning of the output buffer 278207753Smm * \param out_pos The next byte will be written to out[*out_pos]. 279207753Smm * *out_pos is updated only if encoding succeeds. 280207753Smm * \param out_size Size of the out buffer; the first byte into 281207753Smm * which no data is written to is out[out_size]. 282207753Smm */ 283207753Smmextern LZMA_API(lzma_ret) lzma_raw_buffer_decode( 284292588Sdelphij const lzma_filter *filters, const lzma_allocator *allocator, 285207753Smm const uint8_t *in, size_t *in_pos, size_t in_size, 286207753Smm uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow; 287207753Smm 288207753Smm 289207753Smm/** 290207753Smm * \brief Get the size of the Filter Properties field 291207753Smm * 292207753Smm * This function may be useful when implementing custom file formats 293207753Smm * using the raw encoder and decoder. 294207753Smm * 295207753Smm * \param size Pointer to uint32_t to hold the size of the properties 296207753Smm * \param filter Filter ID and options (the size of the properties may 297207753Smm * vary depending on the options) 298207753Smm * 299207753Smm * \return - LZMA_OK 300207753Smm * - LZMA_OPTIONS_ERROR 301207753Smm * - LZMA_PROG_ERROR 302207753Smm * 303207753Smm * \note This function validates the Filter ID, but does not 304207753Smm * necessarily validate the options. Thus, it is possible 305207753Smm * that this returns LZMA_OK while the following call to 306207753Smm * lzma_properties_encode() returns LZMA_OPTIONS_ERROR. 307207753Smm */ 308207753Smmextern LZMA_API(lzma_ret) lzma_properties_size( 309207753Smm uint32_t *size, const lzma_filter *filter) lzma_nothrow; 310207753Smm 311207753Smm 312207753Smm/** 313207753Smm * \brief Encode the Filter Properties field 314207753Smm * 315207753Smm * \param filter Filter ID and options 316207753Smm * \param props Buffer to hold the encoded options. The size of 317207753Smm * buffer must have been already determined with 318207753Smm * lzma_properties_size(). 319207753Smm * 320207753Smm * \return - LZMA_OK 321207753Smm * - LZMA_OPTIONS_ERROR 322207753Smm * - LZMA_PROG_ERROR 323207753Smm * 324207753Smm * \note Even this function won't validate more options than actually 325207753Smm * necessary. Thus, it is possible that encoding the properties 326207753Smm * succeeds but using the same options to initialize the encoder 327207753Smm * will fail. 328207753Smm * 329215187Smm * \note If lzma_properties_size() indicated that the size 330215187Smm * of the Filter Properties field is zero, calling 331215187Smm * lzma_properties_encode() is not required, but it 332215187Smm * won't do any harm either. 333207753Smm */ 334207753Smmextern LZMA_API(lzma_ret) lzma_properties_encode( 335207753Smm const lzma_filter *filter, uint8_t *props) lzma_nothrow; 336207753Smm 337207753Smm 338207753Smm/** 339207753Smm * \brief Decode the Filter Properties field 340207753Smm * 341207753Smm * \param filter filter->id must have been set to the correct 342207753Smm * Filter ID. filter->options doesn't need to be 343207753Smm * initialized (it's not freed by this function). The 344207753Smm * decoded options will be stored to filter->options. 345207753Smm * filter->options is set to NULL if there are no 346207753Smm * properties or if an error occurs. 347207753Smm * \param allocator Custom memory allocator used to allocate the 348207753Smm * options. Set to NULL to use the default malloc(), 349207753Smm * and in case of an error, also free(). 350207753Smm * \param props Input buffer containing the properties. 351207753Smm * \param props_size Size of the properties. This must be the exact 352207753Smm * size; giving too much or too little input will 353207753Smm * return LZMA_OPTIONS_ERROR. 354207753Smm * 355207753Smm * \return - LZMA_OK 356207753Smm * - LZMA_OPTIONS_ERROR 357207753Smm * - LZMA_MEM_ERROR 358207753Smm */ 359207753Smmextern LZMA_API(lzma_ret) lzma_properties_decode( 360292588Sdelphij lzma_filter *filter, const lzma_allocator *allocator, 361207753Smm const uint8_t *props, size_t props_size) lzma_nothrow; 362207753Smm 363207753Smm 364207753Smm/** 365207753Smm * \brief Calculate encoded size of a Filter Flags field 366207753Smm * 367207753Smm * Knowing the size of Filter Flags is useful to know when allocating 368207753Smm * memory to hold the encoded Filter Flags. 369207753Smm * 370207753Smm * \param size Pointer to integer to hold the calculated size 371215187Smm * \param filter Filter ID and associated options whose encoded 372207753Smm * size is to be calculated 373207753Smm * 374207753Smm * \return - LZMA_OK: *size set successfully. Note that this doesn't 375215187Smm * guarantee that filter->options is valid, thus 376207753Smm * lzma_filter_flags_encode() may still fail. 377207753Smm * - LZMA_OPTIONS_ERROR: Unknown Filter ID or unsupported options. 378207753Smm * - LZMA_PROG_ERROR: Invalid options 379207753Smm * 380207753Smm * \note If you need to calculate size of List of Filter Flags, 381207753Smm * you need to loop over every lzma_filter entry. 382207753Smm */ 383207753Smmextern LZMA_API(lzma_ret) lzma_filter_flags_size( 384215187Smm uint32_t *size, const lzma_filter *filter) 385207753Smm lzma_nothrow lzma_attr_warn_unused_result; 386207753Smm 387207753Smm 388207753Smm/** 389207753Smm * \brief Encode Filter Flags into given buffer 390207753Smm * 391207753Smm * In contrast to some functions, this doesn't allocate the needed buffer. 392207753Smm * This is due to how this function is used internally by liblzma. 393207753Smm * 394215187Smm * \param filter Filter ID and options to be encoded 395207753Smm * \param out Beginning of the output buffer 396207753Smm * \param out_pos out[*out_pos] is the next write position. This 397207753Smm * is updated by the encoder. 398207753Smm * \param out_size out[out_size] is the first byte to not write. 399207753Smm * 400207753Smm * \return - LZMA_OK: Encoding was successful. 401207753Smm * - LZMA_OPTIONS_ERROR: Invalid or unsupported options. 402207753Smm * - LZMA_PROG_ERROR: Invalid options or not enough output 403207753Smm * buffer space (you should have checked it with 404207753Smm * lzma_filter_flags_size()). 405207753Smm */ 406215187Smmextern LZMA_API(lzma_ret) lzma_filter_flags_encode(const lzma_filter *filter, 407207753Smm uint8_t *out, size_t *out_pos, size_t out_size) 408207753Smm lzma_nothrow lzma_attr_warn_unused_result; 409207753Smm 410207753Smm 411207753Smm/** 412207753Smm * \brief Decode Filter Flags from given buffer 413207753Smm * 414215187Smm * The decoded result is stored into *filter. The old value of 415215187Smm * filter->options is not free()d. 416207753Smm * 417207753Smm * \return - LZMA_OK 418207753Smm * - LZMA_OPTIONS_ERROR 419207753Smm * - LZMA_MEM_ERROR 420207753Smm * - LZMA_PROG_ERROR 421207753Smm */ 422207753Smmextern LZMA_API(lzma_ret) lzma_filter_flags_decode( 423292588Sdelphij lzma_filter *filter, const lzma_allocator *allocator, 424207753Smm const uint8_t *in, size_t *in_pos, size_t in_size) 425207753Smm lzma_nothrow lzma_attr_warn_unused_result; 426