src/liblzma/api/lzma/info.h

   1 /**
   2  * \file        lzma/info.h
   3  * \brief       Handling of Stream size information
   4  *
   5  * \author      Copyright (C) 1999-2006 Igor Pavlov
   6  * \author      Copyright (C) 2007 Lasse Collin
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2.1 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  */
  18
  19 #ifndef LZMA_H_INTERNAL
  20 #       error Never include this file directly. Use <lzma.h> instead.
  21 #endif
  22
  23
  24 /**********
  25  * Basics *
  26  **********/
  27
  28 /**
  29  * \brief       Opaque data type to hold the size information
  30  */
  31 typedef struct lzma_info_s lzma_info;
  32
  33
  34 typedef struct {
  35         /**
  36          * \brief       Total Size of this Block
  37          *
  38          * This can be LZMA_VLI_VALUE_UNKNOWN.
  39          */
  40         lzma_vli total_size;
  41
  42         /**
  43          * \brief       Uncompressed Size of this Block
  44          *
  45          * This can be LZMA_VLI_VALUE_UNKNOWN.
  46          */
  47         lzma_vli uncompressed_size;
  48
  49         /**
  50          * \brief       Offset of the first byte of the Block
  51          *
  52          * In encoder, this is useful to find out the alignment of the Block.
  53          *
  54          * In decoder, this is useful when doing random-access reading
  55          * with help from lzma_info_data_locate().
  56          */
  57         lzma_vli stream_offset;
  58
  59         /**
  60          * \brief       Uncompressed offset of the Block
  61          *
  62          * Offset of the first uncompressed byte of the Block relative to
  63          * all uncompressed data in the Block.
  64          * FIXME desc
  65          */
  66         lzma_vli uncompressed_offset;
  67
  68         /**
  69          * \brief       Pointers to internal data structures
  70          *
  71          * Applications must not touch these.
  72          */
  73         void *internal[4];
  74
  75 } lzma_info_iter;
  76
  77
  78 typedef enum {
  79         LZMA_INFO_STREAM_START,
  80         LZMA_INFO_HEADER_METADATA,
  81         LZMA_INFO_TOTAL,
  82         LZMA_INFO_UNCOMPRESSED,
  83         LZMA_INFO_FOOTER_METADATA
  84 } lzma_info_size;
  85
  86
  87 /**
  88  * \brief       Allocates and initializes a new lzma_info structure
  89  *
  90  * If info is NULL, a new lzma_info structure is allocated, initialized, and
  91  * a pointer to it returned. If allocation fails, NULL is returned.
  92  *
  93  * If info is non-NULL, it is reinitialized and the same pointer returned.
  94  * (In this case, return value cannot be NULL or a different pointer than
  95  * the info given as argument.)
  96  */
  97 extern lzma_info *lzma_info_init(lzma_info *info, lzma_allocator *allocator);
  98
  99
 100 /**
 101  * \brief       Resets lzma_info
 102  *
 103  * This is like calling lzma_info_end() and lzma_info_create(), but
 104  * re-uses the existing base structure.
 105  */
 106 extern void lzma_info_reset(
 107                 lzma_info *info, lzma_allocator *allocator);
 108
 109
 110 /**
 111  * \brief       Frees memory allocated for a lzma_info structure
 112  */
 113 extern void lzma_info_free(lzma_info *info, lzma_allocator *allocator);
 114
 115
 116 /************************
 117  * Setting known values *
 118  ************************/
 119
 120 /**
 121  * \brief       Set a known size value
 122  *
 123  * \param       info    Pointer returned by lzma_info_create()
 124  * \param       type    Any value from lzma_info_size
 125  * \param       size    Value to set or verify
 126  *
 127  * \return      LZMA_OK on success, LZMA_DATA_ERROR if the size doesn't
 128  *              match the existing information, or LZMA_PROG_ERROR
 129  *              if type is invalid or size is not a valid VLI.
 130  */
 131 extern lzma_ret lzma_info_size_set(
 132                 lzma_info *info, lzma_info_size type, lzma_vli size);
 133
 134
 135 /**
 136  * \brief       Sets the Index
 137  *
 138  * The given lzma_index list is "absorbed" by this function. The application
 139  * must not access it after this function call, even if this function returns
 140  * an error.
 141  *
 142  * \note        The given lzma_index will at some point get freed by the
 143  *              lzma_info_* functions. If you use a custom lzma_allocator,
 144  *              make sure that it can free the lzma_index.
 145  */
 146 extern lzma_ret lzma_info_index_set(
 147                 lzma_info *info, lzma_allocator *allocator,
 148                 lzma_index *index, lzma_bool eat_index);
 149
 150
 151 /**
 152  * \brief       Sets information from a known Metadata Block
 153  *
 154  * This is a shortcut for calling lzma_info_size_set() with different type
 155  * arguments, lzma_info_index_set() with metadata->index.
 156  */
 157 extern lzma_ret lzma_info_metadata_set(lzma_info *info,
 158                 lzma_allocator *allocator, lzma_metadata *metadata,
 159                 lzma_bool is_header_metadata, lzma_bool eat_index);
 160
 161
 162 /***************
 163  * Incremental *
 164  ***************/
 165
 166 /**
 167  * \brief       Prepares an iterator to be used with given lzma_info structure
 168  *
 169  *
 170  */
 171 extern void lzma_info_iter_begin(lzma_info *info, lzma_info_iter *iter);
 172
 173
 174 /**
 175  * \brief       Moves to the next Index Record
 176  *
 177  *
 178  */
 179 extern lzma_ret lzma_info_iter_next(
 180                 lzma_info_iter *iter, lzma_allocator *allocator);
 181
 182
 183 /**
 184  * \brief       Sets or verifies the sizes in the Index Record
 185  *
 186  * \param       iter    Pointer to iterator to be set or verified
 187  * \param       total_size
 188  *                      Total Size in bytes or LZMA_VLI_VALUE_UNKNOWN
 189  * \param       uncompressed_size
 190  *                      Uncompressed Size or LZMA_VLI_VALUE_UNKNOWN
 191  *
 192  * \return      - LZMA_OK: All OK.
 193  *              - LZMA_DATA_ERROR: Given sizes don't match with the already
 194  *                known sizes.
 195  *              - LZMA_PROG_ERROR: Internal error, possibly integer
 196  *                overflow (e.g. the sum of all the known sizes is too big)
 197  */
 198 extern lzma_ret lzma_info_iter_set(lzma_info_iter *iter,
 199                 lzma_vli total_size, lzma_vli uncompressed_size);
 200
 201
 202 /**
 203  * \brief       Locates a Data Block
 204  *
 205  * \param       iter        Properly initialized iterator
 206  * \param       allocator   Pointer to lzma_allocator or NULL
 207  * \param       uncompressed_offset
 208  *                          Target offset to locate. The final offset
 209  *                          will be equal or smaller than this.
 210  * \param       allow_alloc True if this function is allowed to call
 211  *                          lzma_info_iter_next() to allocate a new Record
 212  *                          if the requested offset reached end of Index
 213  *                          Record list. Note that if Index has been marked
 214  *                          final, lzma_info_iter_next() is never called.
 215  *
 216  * \return      - LZMA_OK: All OK, *iter updated accordingly.
 217  *              - LZMA_DATA_ERROR: Trying to search past the end of the Index
 218  *                Record list, and allocating a new Record was not allowed
 219  *                either because allow_alloc was false or Index was final.
 220  *              - LZMA_PROG_ERROR: Internal error (probably integer
 221  *                overflow causing some lzma_vli getting too big).
 222  */
 223 extern lzma_ret lzma_info_iter_locate(lzma_info_iter *iter,
 224                 lzma_allocator *allocator, lzma_vli uncompressed_offset,
 225                 lzma_bool allow_alloc);
 226
 227
 228 /**
 229  * \brief       Finishes incrementally constructed Index
 230  *
 231  * This sets the known Total Size and Uncompressed of the Data Blocks
 232  * based on the information collected from the Index Records, and marks
 233  * the Index as final.
 234  */
 235 extern lzma_ret lzma_info_index_finish(lzma_info *info);
 236
 237
 238 /***************************
 239  * Reading the information *
 240  ***************************/
 241
 242 /**
 243  * \brief       Gets a known size
 244  *
 245  *
 246  */
 247 extern lzma_vli lzma_info_size_get(
 248                 const lzma_info *info, lzma_info_size type);
 249
 250 extern lzma_vli lzma_info_metadata_locate(
 251                 const lzma_info *info, lzma_bool is_header_metadata);
 252
 253 /**
 254  * \brief       Gets a pointer to the beginning of the Index list
 255  *
 256  * If detach is true, the Index will be detached from the lzma_info
 257  * structure, and thus not be modified or freed by lzma_info_end().
 258  *
 259  * If detach is false, the application must not modify the Index in any way.
 260  * Also, the Index list is guaranteed to be valid only till the next call
 261  * to any lzma_info_* function.
 262  */
 263 extern lzma_index *lzma_info_index_get(lzma_info *info, lzma_bool detach);
 264
 265
 266 extern size_t lzma_info_index_count_get(const lzma_info *info);
 267
 268
 269 extern uint32_t lzma_info_metadata_alignment_get(
 270                 const lzma_info *info, lzma_bool is_header_metadata);
 271
 272
 273
 274 /**
 275  * \brief       Locate a Block containing the given uncompressed offset
 276  *
 277  * This function is useful when you need to do random-access reading in
 278  * a Multi-Block Stream.
 279  *
 280  * \param       info    Pointer to lzma_info that has at least one
 281  *                      Index Record. The Index doesn't need to be finished.
 282  * \param       uncompressed_target
 283  *                      Uncompressed target offset which the caller would
 284  *                      like to locate from the Stream.
 285  * \param       stream_offset
 286  *                      Starting offset (relative to the beginning the Stream)
 287  *                      of the Block containing the requested location.
 288  * \param       uncompressed_offset
 289  *                      The actual uncompressed offset of the beginning of
 290  *                      the Block. uncompressed_offset <= uncompressed_target
 291  *                      is always true; the application needs to uncompress
 292  *                      uncompressed_target - uncompressed_offset bytes to
 293  *                      reach the requested target offset.
 294  * \param       total_size
 295  *                      Total Size of the Block. If the Index is incomplete,
 296  *                      this may be LZMA_VLI_VALUE_UNKNOWN indicating unknown
 297  *                      size.
 298  * \param       uncompressed_size
 299  *                      Uncompressed Size of the Block. If the Index is
 300  *                      incomplete, this may be LZMA_VLI_VALUE_UNKNOWN
 301  *                      indicating unknown size. The application must pass
 302  *                      this value to the Block decoder to verify FIXME
 303  *
 304  * \return
 305  *
 306  * \note        This function is currently implemented as a linear search.
 307  *              If there are many Index Records, this can be really slow.
 308  *              This can be improved in newer liblzma versions if needed.
 309  */
 310 extern lzma_bool lzma_info_data_locate(const lzma_info *info,
 311                 lzma_vli uncompressed_target,
 312                 lzma_vli *lzma_restrict stream_offset,
 313                 lzma_vli *lzma_restrict uncompressed_offset,
 314                 lzma_vli *lzma_restrict total_size,
 315                 lzma_vli *lzma_restrict uncompressed_size);