diff options
Diffstat (limited to 'src/liblzma/api/lzma')
| -rw-r--r-- | src/liblzma/api/lzma/block.h | 63 | ||||
| -rw-r--r-- | src/liblzma/api/lzma/container.h | 76 | ||||
| -rw-r--r-- | src/liblzma/api/lzma/lzma.h | 41 |
3 files changed, 123 insertions, 57 deletions
diff --git a/src/liblzma/api/lzma/block.h b/src/liblzma/api/lzma/block.h index 2702cd51..a747b145 100644 --- a/src/liblzma/api/lzma/block.h +++ b/src/liblzma/api/lzma/block.h @@ -33,6 +33,35 @@ */ typedef struct { /** + * \brief Block format version + * + * To prevent API and ABI breakages if new features are needed in + * Block, a version number is used to indicate which fields in this + * structure are in use. For now, version must always be zero. + * With non-zero version, most Block related functions will return + * LZMA_OPTIONS_ERROR. + * + * The decoding functions will always set this to the lowest value + * that supports all the features indicated by the Block Header field. + * The application must check that the version number set by the + * decoding functions is supported by the application. Otherwise it + * is possible that the application will decode the Block incorrectly. + * + * Read by: + * - lzma_block_header_size() + * - lzma_block_header_encode() + * - lzma_block_compressed_size() + * - lzma_block_unpadded_size() + * - lzma_block_total_size() + * - lzma_block_encoder() + * - lzma_block_decoder() + * + * Written by: + * - lzma_block_header_decode() + */ + uint32_t version; + + /** * \brief Size of the Block Header field * * This is always a multiple of four. @@ -168,6 +197,37 @@ typedef struct { */ lzma_filter *filters; + /* + * Reserved space to allow possible future extensions without + * breaking the ABI. You should not touch these, because the names + * of these variables may change. These are and will never be used + * with the currently supported options, so it is safe to leave these + * uninitialized. + */ + void *reserved_ptr1; + void *reserved_ptr2; + void *reserved_ptr3; + uint32_t reserved_int1; + uint32_t reserved_int2; + lzma_vli reserved_int3; + lzma_vli reserved_int4; + lzma_vli reserved_int5; + lzma_vli reserved_int6; + lzma_vli reserved_int7; + lzma_vli reserved_int8; + lzma_reserved_enum reserved_enum1; + lzma_reserved_enum reserved_enum2; + lzma_reserved_enum reserved_enum3; + lzma_reserved_enum reserved_enum4; + lzma_bool reserved_bool1; + lzma_bool reserved_bool2; + lzma_bool reserved_bool3; + lzma_bool reserved_bool4; + lzma_bool reserved_bool5; + lzma_bool reserved_bool6; + lzma_bool reserved_bool7; + lzma_bool reserved_bool8; + } lzma_block; @@ -196,7 +256,8 @@ typedef struct { * * \return - LZMA_OK: Size calculated successfully and stored to * block->header_size. - * - LZMA_OPTIONS_ERROR: Unsupported filters or filter options. + * - LZMA_OPTIONS_ERROR: Unsupported version, filters or + * filter options. * - LZMA_PROG_ERROR: Invalid values like compressed_size == 0. * * \note This doesn't check that all the options are valid i.e. this diff --git a/src/liblzma/api/lzma/container.h b/src/liblzma/api/lzma/container.h index 800f2129..ba2c4f8f 100644 --- a/src/liblzma/api/lzma/container.h +++ b/src/liblzma/api/lzma/container.h @@ -26,30 +26,42 @@ ************/ /** - * \brief Default compression level for easy encoder + * \brief Default compression preset * - * It's not straightforward to recommend a default level, because in some + * It's not straightforward to recommend a default preset, because in some * cases keeping the resource usage relatively low is more important that * getting the maximum compression ratio. */ -#define LZMA_EASY_LEVEL_DEFAULT 6 +#define LZMA_PRESET_DEFAULT UINT32_C(6) + + +/** + * \brief Mask for preset level + * + * This is useful only if you need to extract the level from the preset + * variable. That should be rare. + */ +#define LZMA_PRESET_LEVEL_MASK UINT32_C(0x1F) /* - * Flags for easy encoder + * Preset flags * * Currently only one flag is defined. */ /** - * Use significantly slower compression to get marginally better compression - * ratio. This doesn't affect the memory requirements of the encoder or - * decoder. This flag is useful when you don't mind wasting time to get as - * small result as possible. + * \brief Extreme compression preset + * + * This flag modifies the preset to make the encoding significantly slower + * while improving the compression ratio only marginally. This is useful + * when you don't mind wasting time to get as small result as possible. * - * FIXME: Not implemented yet. + * This flag doesn't affect the memory usage requirements of the decoder (at + * least not significantly). The memory usage of the encoder may be increased + * a little but only at the lowest preset levels (0-4 or so). */ -#define LZMA_EASY_EXTREME UINT32_C(0x01) +#define LZMA_PRESET_EXTREME (UINT32_C(1) << 31) /** @@ -57,12 +69,9 @@ * * This function is a wrapper for lzma_raw_encoder_memusage(). * - * \param level Compression level - * \param flags Easy encoder flags (usually zero). This parameter is - * needed, because in future some flags may affect the - * memory requirements. + * \param preset Compression preset (level and possible flags) */ -extern uint64_t lzma_easy_encoder_memusage(uint32_t level, uint32_t flags) +extern uint64_t lzma_easy_encoder_memusage(uint32_t preset) lzma_attr_pure; @@ -71,12 +80,9 @@ extern uint64_t lzma_easy_encoder_memusage(uint32_t level, uint32_t flags) * * This function is a wrapper for lzma_raw_decoder_memusage(). * - * \param level Compression level - * \param flags Easy encoder flags (usually zero). This parameter is - * needed, because in future some flags may affect the - * memory requirements. + * \param preset Compression preset (level and possible flags) */ -extern uint64_t lzma_easy_decoder_memusage(uint32_t level, uint32_t flags) +extern uint64_t lzma_easy_decoder_memusage(uint32_t preset) lzma_attr_pure; @@ -88,14 +94,12 @@ extern uint64_t lzma_easy_decoder_memusage(uint32_t level, uint32_t flags) * * \param strm Pointer to lzma_stream that is at least initialized * with LZMA_STREAM_INIT. - * \param level Compression level to use. This selects a set of - * compression settings from a list of compression - * presets. Currently levels from 1 to 9 are defined, - * which match the options -1 .. -9 of the xz command - * line tool. - * \param flags Flags that can finetune the compression preset. - * In most cases, no flags are wanted, and this - * parameter is zero. + * \param preset Compression preset to use. A preset consist of level + * number and zero or more flags. Usually flags aren't + * used, so preset is simply a number [0, 9] which match + * the options -0 .. -9 of the xz command line tool. + * Additional flags can be be set using bitwise-or with + * the preset level number, e.g. 6 | LZMA_PRESET_EXTREME. * \param check Integrity check type to use. See check.h for available * checks. If you are unsure, use LZMA_CHECK_CRC32. * @@ -115,8 +119,8 @@ extern uint64_t lzma_easy_decoder_memusage(uint32_t level, uint32_t flags) * LZMA_RUN, LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, and LZMA_FINISH. In future, * there may be compression levels or flags that don't support LZMA_SYNC_FLUSH. */ -extern lzma_ret lzma_easy_encoder(lzma_stream *strm, - uint32_t level, uint32_t flags, lzma_check check) +extern lzma_ret lzma_easy_encoder( + lzma_stream *strm, uint32_t preset, lzma_check check) lzma_attr_warn_unused_result; @@ -125,10 +129,8 @@ extern lzma_ret lzma_easy_encoder(lzma_stream *strm, * * \param strm Pointer to properly prepared lzma_stream * \param filters Array of filters. This must be terminated with - * filters[n].id = LZMA_VLI_UNKNOWN. There must - * be 1-4 filters, but there are restrictions on how - * multiple filters can be combined. FIXME Tell where - * to find more information. + * filters[n].id = LZMA_VLI_UNKNOWN. See filter.h for + * more information. * \param check Type of the integrity check to calculate from * uncompressed data. * @@ -153,15 +155,13 @@ extern lzma_ret lzma_stream_encoder(lzma_stream *strm, * legacy LZMA tools such as LZMA Utils 4.32.x. Moving to the .xz format * is strongly recommended. * - * FIXME: Dictionary size limit? - * * The valid action values for lzma_code() are LZMA_RUN and LZMA_FINISH. * No kind of flushing is supported, because the file format doesn't make * it possible. * * \return - LZMA_OK * - LZMA_MEM_ERROR - * - LZMA_OPTIONS_ERROR // FIXME + * - LZMA_OPTIONS_ERROR * - LZMA_PROG_ERROR */ extern lzma_ret lzma_alone_encoder( @@ -252,7 +252,7 @@ extern lzma_ret lzma_auto_decoder( /** - * \brief Initializes decoder for .lzma file + * \brief Initialize .lzma decoder (legacy file format) * * Valid `action' arguments to lzma_code() are LZMA_RUN and LZMA_FINISH. * There is no need to use LZMA_FINISH, but allowing it may simplify diff --git a/src/liblzma/api/lzma/lzma.h b/src/liblzma/api/lzma/lzma.h index e3db236b..834bf0b0 100644 --- a/src/liblzma/api/lzma/lzma.h +++ b/src/liblzma/api/lzma/lzma.h @@ -160,19 +160,20 @@ typedef enum { * mode, which the application developer wasn't aware, could require giving * additional options to the encoder that the older modes don't need. */ -extern lzma_bool lzma_mode_is_available(lzma_mode mode) lzma_attr_const; +extern lzma_bool lzma_mode_is_supported(lzma_mode mode) lzma_attr_const; /** * \brief Options specific to the LZMA1 and LZMA2 filters + * + * Since LZMA1 and LZMA2 share most of the code, it's simplest to share + * the options structure too. For encoding, all but the reserved variables + * need to be initialized unless specifically mentioned otherwise. + * + * For raw decoding, both LZMA1 and LZMA2 need dict_size, preset_dict, and + * preset_dict_size (if preset_dict != NULL). LZMA1 needs also lc, lp, and pb. */ typedef struct { - /********************************** - * LZMA encoding/decoding options * - **********************************/ - - /* These options are required in encoder and also with raw decoding. */ - /** * \brief Dictionary size in bytes * @@ -298,10 +299,6 @@ typedef struct { # define LZMA_PB_MAX 4 # define LZMA_PB_DEFAULT 2 - /****************************************** - * LZMA options needed only when encoding * - ******************************************/ - /** * \brief Indicate if the options structure is persistent * @@ -377,6 +374,8 @@ typedef struct { * with the currently supported options, so it is safe to leave these * uninitialized. */ + void *reserved_ptr1; + void *reserved_ptr2; uint32_t reserved_int1; uint32_t reserved_int2; uint32_t reserved_int3; @@ -385,20 +384,26 @@ typedef struct { uint32_t reserved_int6; uint32_t reserved_int7; uint32_t reserved_int8; - void *reserved_ptr1; - void *reserved_ptr2; + lzma_reserved_enum reserved_enum1; + lzma_reserved_enum reserved_enum2; + lzma_reserved_enum reserved_enum3; + lzma_reserved_enum reserved_enum4; } lzma_options_lzma; /** - * \brief Set a compression level preset to lzma_options_lzma structure + * \brief Set a compression preset to lzma_options_lzma structure * - * level = 1 is the fastest and level = 9 is the slowest. These presets match - * the switches -1 .. -9 of the command line tool. + * 0 is the fastest and 9 is the slowest. These match the switches -0 .. -9 + * of the xz command line tool. In addition, it is possible to bitwise-or + * flags to the preset. Currently only LZMA_PRESET_EXTREME is supported. + * The flags are defined in container.h, because the flags are used also + * with lzma_easy_encoder(). * * The preset values are subject to changes between liblzma versions. * - * This function is available only if LZMA encoder has been enabled. + * This function is available only if LZMA1 or LZMA2 encoder has been enabled + * when building liblzma. */ -extern lzma_bool lzma_lzma_preset(lzma_options_lzma *options, uint32_t level); +extern lzma_bool lzma_lzma_preset(lzma_options_lzma *options, uint32_t preset); |