| /** |
| * \file lzma/info.h |
| * \brief Handling of Stream size information |
| * |
| * \author Copyright (C) 1999-2006 Igor Pavlov |
| * \author Copyright (C) 2007 Lasse Collin |
| * |
| * This library is free software; you can redistribute it and/or |
| * modify it under the terms of the GNU Lesser General Public |
| * License as published by the Free Software Foundation; either |
| * version 2.1 of the License, or (at your option) any later version. |
| * |
| * This library is distributed in the hope that it will be useful, |
| * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| * Lesser General Public License for more details. |
| */ |
| |
| #ifndef LZMA_H_INTERNAL |
| # error Never include this file directly. Use <lzma.h> instead. |
| #endif |
| |
| |
| /********** |
| * Basics * |
| **********/ |
| |
| /** |
| * \brief Opaque data type to hold the size information |
| */ |
| typedef struct lzma_info_s lzma_info; |
| |
| |
| typedef struct { |
| /** |
| * \brief Total Size of this Block |
| * |
| * This can be LZMA_VLI_VALUE_UNKNOWN. |
| */ |
| lzma_vli total_size; |
| |
| /** |
| * \brief Uncompressed Size of this Block |
| * |
| * This can be LZMA_VLI_VALUE_UNKNOWN. |
| */ |
| lzma_vli uncompressed_size; |
| |
| /** |
| * \brief Offset of the first byte of the Block |
| * |
| * In encoder, this is useful to find out the alignment of the Block. |
| * |
| * In decoder, this is useful when doing random-access reading |
| * with help from lzma_info_data_locate(). |
| */ |
| lzma_vli stream_offset; |
| |
| /** |
| * \brief Uncompressed offset of the Block |
| * |
| * Offset of the first uncompressed byte of the Block relative to |
| * all uncompressed data in the Block. |
| * FIXME desc |
| */ |
| lzma_vli uncompressed_offset; |
| |
| /** |
| * \brief Pointers to internal data structures |
| * |
| * Applications must not touch these. |
| */ |
| void *internal[4]; |
| |
| } lzma_info_iter; |
| |
| |
| typedef enum { |
| LZMA_INFO_STREAM_START, |
| LZMA_INFO_HEADER_METADATA, |
| LZMA_INFO_TOTAL, |
| LZMA_INFO_UNCOMPRESSED, |
| LZMA_INFO_FOOTER_METADATA |
| } lzma_info_size; |
| |
| |
| /** |
| * \brief Allocates and initializes a new lzma_info structure |
| * |
| * If info is NULL, a new lzma_info structure is allocated, initialized, and |
| * a pointer to it returned. If allocation fails, NULL is returned. |
| * |
| * If info is non-NULL, it is reinitialized and the same pointer returned. |
| * (In this case, return value cannot be NULL or a different pointer than |
| * the info given as argument.) |
| */ |
| extern lzma_info *lzma_info_init(lzma_info *info, lzma_allocator *allocator); |
| |
| |
| /** |
| * \brief Resets lzma_info |
| * |
| * This is like calling lzma_info_end() and lzma_info_create(), but |
| * re-uses the existing base structure. |
| */ |
| extern void lzma_info_reset( |
| lzma_info *info, lzma_allocator *allocator); |
| |
| |
| /** |
| * \brief Frees memory allocated for a lzma_info structure |
| */ |
| extern void lzma_info_free(lzma_info *info, lzma_allocator *allocator); |
| |
| |
| /************************ |
| * Setting known values * |
| ************************/ |
| |
| /** |
| * \brief Set a known size value |
| * |
| * \param info Pointer returned by lzma_info_create() |
| * \param type Any value from lzma_info_size |
| * \param size Value to set or verify |
| * |
| * \return LZMA_OK on success, LZMA_DATA_ERROR if the size doesn't |
| * match the existing information, or LZMA_PROG_ERROR |
| * if type is invalid or size is not a valid VLI. |
| */ |
| extern lzma_ret lzma_info_size_set( |
| lzma_info *info, lzma_info_size type, lzma_vli size); |
| |
| |
| /** |
| * \brief Sets the Index |
| * |
| * The given lzma_index list is "absorbed" by this function. The application |
| * must not access it after this function call, even if this function returns |
| * an error. |
| * |
| * \note The given lzma_index will at some point get freed by the |
| * lzma_info_* functions. If you use a custom lzma_allocator, |
| * make sure that it can free the lzma_index. |
| */ |
| extern lzma_ret lzma_info_index_set( |
| lzma_info *info, lzma_allocator *allocator, |
| lzma_index *index, lzma_bool eat_index); |
| |
| |
| /** |
| * \brief Sets information from a known Metadata Block |
| * |
| * This is a shortcut for calling lzma_info_size_set() with different type |
| * arguments, lzma_info_index_set() with metadata->index. |
| */ |
| extern lzma_ret lzma_info_metadata_set(lzma_info *info, |
| lzma_allocator *allocator, lzma_metadata *metadata, |
| lzma_bool is_header_metadata, lzma_bool eat_index); |
| |
| |
| /*************** |
| * Incremental * |
| ***************/ |
| |
| /** |
| * \brief Prepares an iterator to be used with given lzma_info structure |
| * |
| * |
| */ |
| extern void lzma_info_iter_begin(lzma_info *info, lzma_info_iter *iter); |
| |
| |
| /** |
| * \brief Moves to the next Index Record |
| * |
| * |
| */ |
| extern lzma_ret lzma_info_iter_next( |
| lzma_info_iter *iter, lzma_allocator *allocator); |
| |
| |
| /** |
| * \brief Sets or verifies the sizes in the Index Record |
| * |
| * \param iter Pointer to iterator to be set or verified |
| * \param total_size |
| * Total Size in bytes or LZMA_VLI_VALUE_UNKNOWN |
| * \param uncompressed_size |
| * Uncompressed Size or LZMA_VLI_VALUE_UNKNOWN |
| * |
| * \return - LZMA_OK: All OK. |
| * - LZMA_DATA_ERROR: Given sizes don't match with the already |
| * known sizes. |
| * - LZMA_PROG_ERROR: Internal error, possibly integer |
| * overflow (e.g. the sum of all the known sizes is too big) |
| */ |
| extern lzma_ret lzma_info_iter_set(lzma_info_iter *iter, |
| lzma_vli total_size, lzma_vli uncompressed_size); |
| |
| |
| /** |
| * \brief Locates a Data Block |
| * |
| * \param iter Properly initialized iterator |
| * \param allocator Pointer to lzma_allocator or NULL |
| * \param uncompressed_offset |
| * Target offset to locate. The final offset |
| * will be equal or smaller than this. |
| * \param allow_alloc True if this function is allowed to call |
| * lzma_info_iter_next() to allocate a new Record |
| * if the requested offset reached end of Index |
| * Record list. Note that if Index has been marked |
| * final, lzma_info_iter_next() is never called. |
| * |
| * \return - LZMA_OK: All OK, *iter updated accordingly. |
| * - LZMA_DATA_ERROR: Trying to search past the end of the Index |
| * Record list, and allocating a new Record was not allowed |
| * either because allow_alloc was false or Index was final. |
| * - LZMA_PROG_ERROR: Internal error (probably integer |
| * overflow causing some lzma_vli getting too big). |
| */ |
| extern lzma_ret lzma_info_iter_locate(lzma_info_iter *iter, |
| lzma_allocator *allocator, lzma_vli uncompressed_offset, |
| lzma_bool allow_alloc); |
| |
| |
| /** |
| * \brief Finishes incrementally constructed Index |
| * |
| * This sets the known Total Size and Uncompressed of the Data Blocks |
| * based on the information collected from the Index Records, and marks |
| * the Index as final. |
| */ |
| extern lzma_ret lzma_info_index_finish(lzma_info *info); |
| |
| |
| /*************************** |
| * Reading the information * |
| ***************************/ |
| |
| /** |
| * \brief Gets a known size |
| * |
| * |
| */ |
| extern lzma_vli lzma_info_size_get( |
| const lzma_info *info, lzma_info_size type); |
| |
| extern lzma_vli lzma_info_metadata_locate( |
| const lzma_info *info, lzma_bool is_header_metadata); |
| |
| /** |
| * \brief Gets a pointer to the beginning of the Index list |
| * |
| * If detach is true, the Index will be detached from the lzma_info |
| * structure, and thus not be modified or freed by lzma_info_end(). |
| * |
| * If detach is false, the application must not modify the Index in any way. |
| * Also, the Index list is guaranteed to be valid only till the next call |
| * to any lzma_info_* function. |
| */ |
| extern lzma_index *lzma_info_index_get(lzma_info *info, lzma_bool detach); |
| |
| |
| extern size_t lzma_info_index_count_get(const lzma_info *info); |
| |
| |
| extern uint32_t lzma_info_metadata_alignment_get( |
| const lzma_info *info, lzma_bool is_header_metadata); |
| |
| |
| |
| /** |
| * \brief Locate a Block containing the given uncompressed offset |
| * |
| * This function is useful when you need to do random-access reading in |
| * a Multi-Block Stream. |
| * |
| * \param info Pointer to lzma_info that has at least one |
| * Index Record. The Index doesn't need to be finished. |
| * \param uncompressed_target |
| * Uncompressed target offset which the caller would |
| * like to locate from the Stream. |
| * \param stream_offset |
| * Starting offset (relative to the beginning the Stream) |
| * of the Block containing the requested location. |
| * \param uncompressed_offset |
| * The actual uncompressed offset of the beginning of |
| * the Block. uncompressed_offset <= uncompressed_target |
| * is always true; the application needs to uncompress |
| * uncompressed_target - uncompressed_offset bytes to |
| * reach the requested target offset. |
| * \param total_size |
| * Total Size of the Block. If the Index is incomplete, |
| * this may be LZMA_VLI_VALUE_UNKNOWN indicating unknown |
| * size. |
| * \param uncompressed_size |
| * Uncompressed Size of the Block. If the Index is |
| * incomplete, this may be LZMA_VLI_VALUE_UNKNOWN |
| * indicating unknown size. The application must pass |
| * this value to the Block decoder to verify FIXME |
| * |
| * \return |
| * |
| * \note This function is currently implemented as a linear search. |
| * If there are many Index Records, this can be really slow. |
| * This can be improved in newer liblzma versions if needed. |
| */ |
| extern lzma_bool lzma_info_data_locate(const lzma_info *info, |
| lzma_vli uncompressed_target, |
| lzma_vli *lzma_restrict stream_offset, |
| lzma_vli *lzma_restrict uncompressed_offset, |
| lzma_vli *lzma_restrict total_size, |
| lzma_vli *lzma_restrict uncompressed_size); |
