src/liblzma/api/lzma/index.h

   1 /**
   2  * \file        lzma/index.h
   3  * \brief       Handling of Index lists
   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  * \brief       Opaque data type to hold the Index
  26  */
  27 typedef struct lzma_index_s lzma_index;
  28
  29
  30 /**
  31  * \brief       Index Record and its location
  32  */
  33 typedef struct {
  34         /**
  35          * Total Size of a Block.
  36          */
  37         lzma_vli total_size;
  38
  39         /**
  40          * Uncompressed Size of a Block
  41          */
  42         lzma_vli uncompressed_size;
  43
  44         /**
  45          * Offset of the first byte of a Block relative to the beginning
  46          * of the Stream, or if there are multiple Indexes combined,
  47          * relative to the beginning of the first Stream.
  48          */
  49         lzma_vli stream_offset;
  50
  51         /**
  52          * Uncompressed offset
  53          */
  54         lzma_vli uncompressed_offset;
  55
  56 } lzma_index_record;
  57
  58
  59 /**
  60  * \brief       Allocate and initialize a new lzma_index structure
  61  *
  62  * If i is NULL, a new lzma_index structure is allocated, initialized,
  63  * and a pointer to it returned. If allocation fails, NULL is returned.
  64  *
  65  * If i is non-NULL, it is reinitialized and the same pointer returned.
  66  * In this case, return value cannot be NULL or a different pointer than
  67  * the i given as argument.
  68  */
  69 extern lzma_index *lzma_index_init(lzma_index *i, lzma_allocator *allocator)
  70                 lzma_attr_warn_unused_result;
  71
  72
  73 /**
  74  * \brief       Deallocate the Index
  75  */
  76 extern void lzma_index_end(lzma_index *i, lzma_allocator *allocator);
  77
  78
  79 /**
  80  * \brief       Add a new Record to an Index
  81  *
  82  * \param       index             Pointer to a lzma_index structure
  83  * \param       total_size        Total Size of a Block
  84  * \param       uncompressed_size Uncompressed Size of a Block, or
  85  *                                LZMA_VLI_UNKNOWN to indicate padding.
  86  *
  87  * Appending a new Record does not affect the read position.
  88  *
  89  * \return      - LZMA_OK
  90  *              - LZMA_DATA_ERROR: Compressed or uncompressed size of the
  91  *                Stream or size of the Index field would grow too big.
  92  *              - LZMA_PROG_ERROR
  93  */
  94 extern lzma_ret lzma_index_append(lzma_index *i, lzma_allocator *allocator,
  95                 lzma_vli total_size, lzma_vli uncompressed_size)
  96                 lzma_attr_warn_unused_result;
  97
  98
  99 /**
 100  * \brief       Get the number of Records
 101  */
 102 extern lzma_vli lzma_index_count(const lzma_index *i) lzma_attr_pure;
 103
 104
 105 /**
 106  * \brief       Get the size of the Index field as bytes
 107  *
 108  * This is needed to verify the Index Size field from the Stream Footer.
 109  */
 110 extern lzma_vli lzma_index_size(const lzma_index *i) lzma_attr_pure;
 111
 112
 113 /**
 114  * \brief       Get the total size of the Blocks
 115  *
 116  * This doesn't include the Stream Header, Stream Footer, Stream Padding,
 117  * or Index fields.
 118  */
 119 extern lzma_vli lzma_index_total_size(const lzma_index *i) lzma_attr_pure;
 120
 121
 122 /**
 123  * \brief       Get the total size of the Stream
 124  *
 125  * If multiple Indexes have been combined, this works as if the Blocks
 126  * were in a single Stream.
 127  */
 128 extern lzma_vli lzma_index_stream_size(const lzma_index *i) lzma_attr_pure;
 129
 130
 131 /**
 132  * \brief       Get the total size of the file
 133  *
 134  * When no Indexes have been combined with lzma_index_cat(), this function is
 135  * identical to lzma_index_stream_size(). If multiple Indexes have been
 136  * combined, this includes also the possible Stream Padding fields.
 137  */
 138 extern lzma_vli lzma_index_file_size(const lzma_index *i) lzma_attr_pure;
 139
 140
 141 /**
 142  * \brief       Get the uncompressed size of the Stream
 143  */
 144 extern lzma_vli lzma_index_uncompressed_size(const lzma_index *i)
 145                 lzma_attr_pure;
 146
 147
 148 /**
 149  * \brief       Get the next Record from the Index
 150  */
 151 extern lzma_bool lzma_index_read(lzma_index *i, lzma_index_record *record)
 152                 lzma_attr_warn_unused_result;
 153
 154
 155 /**
 156  * \brief       Rewind the Index
 157  *
 158  * Rewind the Index so that next call to lzma_index_read() will return the
 159  * first Record.
 160  */
 161 extern void lzma_index_rewind(lzma_index *i);
 162
 163
 164 /**
 165  * \brief       Locate a Record
 166  *
 167  * When the Index is available, it is possible to do random-access reading
 168  * with granularity of Block size.
 169  *
 170  * \param       i       Pointer to lzma_index structure
 171  * \param       record  Pointer to a structure to hold the search results
 172  * \param       target  Uncompressed target offset
 173  *
 174  * If the target is smaller than the uncompressed size of the Stream (can be
 175  * checked with lzma_index_uncompressed_size()):
 176  *  - Information about the Record containing the requested uncompressed
 177  *    offset is stored into *record.
 178  *  - Read offset will be adjusted so that calling lzma_index_read() can be
 179  *    used to read subsequent Records.
 180  *  - This function returns false.
 181  *
 182  * If target is greater than the uncompressed size of the Stream, *record
 183  * and the read position are not modified, and this function returns true.
 184  */
 185 extern lzma_bool lzma_index_locate(
 186                 lzma_index *i, lzma_index_record *record, lzma_vli target)
 187                 lzma_attr_warn_unused_result;
 188
 189
 190 /**
 191  * \brief       Concatenate Indexes of two Streams
 192  *
 193  *
 194  *
 195  * \param       dest      Destination Index after which src is appended Source
 196  * \param       src       Index. The memory allocated for this is either moved
 197  *                        to be part of *dest or freed iff the function call
 198  *                        succeeds, and src will be an invalid pointer.
 199  * \param       allocator Custom memory allocator; can be NULL to use
 200  *                        malloc() and free().
 201  * \param       padding   Size of the Stream Padding field between Streams.
 202  *
 203  * \return      - LZMA_OK: Indexes concatenated successfully.
 204  *              - LZMA_DATA_ERROR: *dest would grow too big.
 205  *              - LZMA_MEM_ERROR
 206  *              - LZMA_PROG_ERROR
 207  */
 208 extern lzma_ret lzma_index_cat(lzma_index *lzma_restrict dest,
 209                 lzma_index *lzma_restrict src,
 210                 lzma_allocator *allocator, lzma_vli padding)
 211                 lzma_attr_warn_unused_result;
 212
 213
 214 /**
 215  * \brief       Duplicates an Index list
 216  *
 217  * \return      A copy of the Index, or NULL if memory allocation failed.
 218  */
 219 extern lzma_index *lzma_index_dup(
 220                 const lzma_index *i, lzma_allocator *allocator)
 221                 lzma_attr_warn_unused_result;
 222
 223
 224 /**
 225  * \brief       Compares if two Index lists are identical
 226  */
 227 extern lzma_bool lzma_index_equal(const lzma_index *a, const lzma_index *b)
 228                 lzma_attr_pure;
 229
 230
 231 /**
 232  * \brief       Initializes Index encoder
 233  */
 234 extern lzma_ret lzma_index_encoder(lzma_stream *strm, lzma_index *i)
 235                 lzma_attr_warn_unused_result;
 236
 237
 238 /**
 239  * \brief       Initializes Index decoder
 240  */
 241 extern lzma_ret lzma_index_decoder(lzma_stream *strm, lzma_index **i)
 242                 lzma_attr_warn_unused_result;