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