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