root / lab4 / .minix-src / include / lzma / index.h @ 13
History | View | Annotate | Download (22.7 KB)
| 1 | 13 | up20180614 | /**
|
|---|---|---|---|
| 2 | * \file lzma/index.h
|
||
| 3 | * \brief Handling of .xz Index and related information
|
||
| 4 | */
|
||
| 5 | |||
| 6 | /*
|
||
| 7 | * Author: Lasse Collin
|
||
| 8 | *
|
||
| 9 | * This file has been put into the public domain.
|
||
| 10 | * You can do whatever you want with this file.
|
||
| 11 | *
|
||
| 12 | * See ../lzma.h for information about liblzma as a whole.
|
||
| 13 | */
|
||
| 14 | |||
| 15 | #ifndef LZMA_H_INTERNAL
|
||
| 16 | # error Never include this file directly. Use <lzma.h> instead.
|
||
| 17 | #endif
|
||
| 18 | |||
| 19 | |||
| 20 | /**
|
||
| 21 | * \brief Opaque data type to hold the Index(es) and other information
|
||
| 22 | *
|
||
| 23 | * lzma_index often holds just one .xz Index and possibly the Stream Flags
|
||
| 24 | * of the same Stream and size of the Stream Padding field. However,
|
||
| 25 | * multiple lzma_indexes can be concatenated with lzma_index_cat() and then
|
||
| 26 | * there may be information about multiple Streams in the same lzma_index.
|
||
| 27 | *
|
||
| 28 | * Notes about thread safety: Only one thread may modify lzma_index at
|
||
| 29 | * a time. All functions that take non-const pointer to lzma_index
|
||
| 30 | * modify it. As long as no thread is modifying the lzma_index, getting
|
||
| 31 | * information from the same lzma_index can be done from multiple threads
|
||
| 32 | * at the same time with functions that take a const pointer to
|
||
| 33 | * lzma_index or use lzma_index_iter. The same iterator must be used
|
||
| 34 | * only by one thread at a time, of course, but there can be as many
|
||
| 35 | * iterators for the same lzma_index as needed.
|
||
| 36 | */
|
||
| 37 | typedef struct lzma_index_s lzma_index; |
||
| 38 | |||
| 39 | |||
| 40 | /**
|
||
| 41 | * \brief Iterator to get information about Blocks and Streams
|
||
| 42 | */
|
||
| 43 | typedef struct { |
||
| 44 | struct {
|
||
| 45 | /**
|
||
| 46 | * \brief Pointer to Stream Flags
|
||
| 47 | *
|
||
| 48 | * This is NULL if Stream Flags have not been set for
|
||
| 49 | * this Stream with lzma_index_stream_flags().
|
||
| 50 | */
|
||
| 51 | const lzma_stream_flags *flags;
|
||
| 52 | |||
| 53 | const void *reserved_ptr1; |
||
| 54 | const void *reserved_ptr2; |
||
| 55 | const void *reserved_ptr3; |
||
| 56 | |||
| 57 | /**
|
||
| 58 | * \brief Stream number in the lzma_index
|
||
| 59 | *
|
||
| 60 | * The first Stream is 1.
|
||
| 61 | */
|
||
| 62 | lzma_vli number; |
||
| 63 | |||
| 64 | /**
|
||
| 65 | * \brief Number of Blocks in the Stream
|
||
| 66 | *
|
||
| 67 | * If this is zero, the block structure below has
|
||
| 68 | * undefined values.
|
||
| 69 | */
|
||
| 70 | lzma_vli block_count; |
||
| 71 | |||
| 72 | /**
|
||
| 73 | * \brief Compressed start offset of this Stream
|
||
| 74 | *
|
||
| 75 | * The offset is relative to the beginning of the lzma_index
|
||
| 76 | * (i.e. usually the beginning of the .xz file).
|
||
| 77 | */
|
||
| 78 | lzma_vli compressed_offset; |
||
| 79 | |||
| 80 | /**
|
||
| 81 | * \brief Uncompressed start offset of this Stream
|
||
| 82 | *
|
||
| 83 | * The offset is relative to the beginning of the lzma_index
|
||
| 84 | * (i.e. usually the beginning of the .xz file).
|
||
| 85 | */
|
||
| 86 | lzma_vli uncompressed_offset; |
||
| 87 | |||
| 88 | /**
|
||
| 89 | * \brief Compressed size of this Stream
|
||
| 90 | *
|
||
| 91 | * This includes all headers except the possible
|
||
| 92 | * Stream Padding after this Stream.
|
||
| 93 | */
|
||
| 94 | lzma_vli compressed_size; |
||
| 95 | |||
| 96 | /**
|
||
| 97 | * \brief Uncompressed size of this Stream
|
||
| 98 | */
|
||
| 99 | lzma_vli uncompressed_size; |
||
| 100 | |||
| 101 | /**
|
||
| 102 | * \brief Size of Stream Padding after this Stream
|
||
| 103 | *
|
||
| 104 | * If it hasn't been set with lzma_index_stream_padding(),
|
||
| 105 | * this defaults to zero. Stream Padding is always
|
||
| 106 | * a multiple of four bytes.
|
||
| 107 | */
|
||
| 108 | lzma_vli padding; |
||
| 109 | |||
| 110 | lzma_vli reserved_vli1; |
||
| 111 | lzma_vli reserved_vli2; |
||
| 112 | lzma_vli reserved_vli3; |
||
| 113 | lzma_vli reserved_vli4; |
||
| 114 | } stream; |
||
| 115 | |||
| 116 | struct {
|
||
| 117 | /**
|
||
| 118 | * \brief Block number in the file
|
||
| 119 | *
|
||
| 120 | * The first Block is 1.
|
||
| 121 | */
|
||
| 122 | lzma_vli number_in_file; |
||
| 123 | |||
| 124 | /**
|
||
| 125 | * \brief Compressed start offset of this Block
|
||
| 126 | *
|
||
| 127 | * This offset is relative to the beginning of the
|
||
| 128 | * lzma_index (i.e. usually the beginning of the .xz file).
|
||
| 129 | * Normally this is where you should seek in the .xz file
|
||
| 130 | * to start decompressing this Block.
|
||
| 131 | */
|
||
| 132 | lzma_vli compressed_file_offset; |
||
| 133 | |||
| 134 | /**
|
||
| 135 | * \brief Uncompressed start offset of this Block
|
||
| 136 | *
|
||
| 137 | * This offset is relative to the beginning of the lzma_index
|
||
| 138 | * (i.e. usually the beginning of the .xz file).
|
||
| 139 | *
|
||
| 140 | * When doing random-access reading, it is possible that
|
||
| 141 | * the target offset is not exactly at Block boundary. One
|
||
| 142 | * will need to compare the target offset against
|
||
| 143 | * uncompressed_file_offset or uncompressed_stream_offset,
|
||
| 144 | * and possibly decode and throw away some amount of data
|
||
| 145 | * before reaching the target offset.
|
||
| 146 | */
|
||
| 147 | lzma_vli uncompressed_file_offset; |
||
| 148 | |||
| 149 | /**
|
||
| 150 | * \brief Block number in this Stream
|
||
| 151 | *
|
||
| 152 | * The first Block is 1.
|
||
| 153 | */
|
||
| 154 | lzma_vli number_in_stream; |
||
| 155 | |||
| 156 | /**
|
||
| 157 | * \brief Compressed start offset of this Block
|
||
| 158 | *
|
||
| 159 | * This offset is relative to the beginning of the Stream
|
||
| 160 | * containing this Block.
|
||
| 161 | */
|
||
| 162 | lzma_vli compressed_stream_offset; |
||
| 163 | |||
| 164 | /**
|
||
| 165 | * \brief Uncompressed start offset of this Block
|
||
| 166 | *
|
||
| 167 | * This offset is relative to the beginning of the Stream
|
||
| 168 | * containing this Block.
|
||
| 169 | */
|
||
| 170 | lzma_vli uncompressed_stream_offset; |
||
| 171 | |||
| 172 | /**
|
||
| 173 | * \brief Uncompressed size of this Block
|
||
| 174 | *
|
||
| 175 | * You should pass this to the Block decoder if you will
|
||
| 176 | * decode this Block. It will allow the Block decoder to
|
||
| 177 | * validate the uncompressed size.
|
||
| 178 | */
|
||
| 179 | lzma_vli uncompressed_size; |
||
| 180 | |||
| 181 | /**
|
||
| 182 | * \brief Unpadded size of this Block
|
||
| 183 | *
|
||
| 184 | * You should pass this to the Block decoder if you will
|
||
| 185 | * decode this Block. It will allow the Block decoder to
|
||
| 186 | * validate the unpadded size.
|
||
| 187 | */
|
||
| 188 | lzma_vli unpadded_size; |
||
| 189 | |||
| 190 | /**
|
||
| 191 | * \brief Total compressed size
|
||
| 192 | *
|
||
| 193 | * This includes all headers and padding in this Block.
|
||
| 194 | * This is useful if you need to know how many bytes
|
||
| 195 | * the Block decoder will actually read.
|
||
| 196 | */
|
||
| 197 | lzma_vli total_size; |
||
| 198 | |||
| 199 | lzma_vli reserved_vli1; |
||
| 200 | lzma_vli reserved_vli2; |
||
| 201 | lzma_vli reserved_vli3; |
||
| 202 | lzma_vli reserved_vli4; |
||
| 203 | |||
| 204 | const void *reserved_ptr1; |
||
| 205 | const void *reserved_ptr2; |
||
| 206 | const void *reserved_ptr3; |
||
| 207 | const void *reserved_ptr4; |
||
| 208 | } block; |
||
| 209 | |||
| 210 | /*
|
||
| 211 | * Internal data which is used to store the state of the iterator.
|
||
| 212 | * The exact format may vary between liblzma versions, so don't
|
||
| 213 | * touch these in any way.
|
||
| 214 | */
|
||
| 215 | union {
|
||
| 216 | const void *p; |
||
| 217 | size_t s; |
||
| 218 | lzma_vli v; |
||
| 219 | } internal[6];
|
||
| 220 | } lzma_index_iter; |
||
| 221 | |||
| 222 | |||
| 223 | /**
|
||
| 224 | * \brief Operation mode for lzma_index_iter_next()
|
||
| 225 | */
|
||
| 226 | typedef enum { |
||
| 227 | LZMA_INDEX_ITER_ANY = 0,
|
||
| 228 | /**<
|
||
| 229 | * \brief Get the next Block or Stream
|
||
| 230 | *
|
||
| 231 | * Go to the next Block if the current Stream has at least
|
||
| 232 | * one Block left. Otherwise go to the next Stream even if
|
||
| 233 | * it has no Blocks. If the Stream has no Blocks
|
||
| 234 | * (lzma_index_iter.stream.block_count == 0),
|
||
| 235 | * lzma_index_iter.block will have undefined values.
|
||
| 236 | */
|
||
| 237 | |||
| 238 | LZMA_INDEX_ITER_STREAM = 1,
|
||
| 239 | /**<
|
||
| 240 | * \brief Get the next Stream
|
||
| 241 | *
|
||
| 242 | * Go to the next Stream even if the current Stream has
|
||
| 243 | * unread Blocks left. If the next Stream has at least one
|
||
| 244 | * Block, the iterator will point to the first Block.
|
||
| 245 | * If there are no Blocks, lzma_index_iter.block will have
|
||
| 246 | * undefined values.
|
||
| 247 | */
|
||
| 248 | |||
| 249 | LZMA_INDEX_ITER_BLOCK = 2,
|
||
| 250 | /**<
|
||
| 251 | * \brief Get the next Block
|
||
| 252 | *
|
||
| 253 | * Go to the next Block if the current Stream has at least
|
||
| 254 | * one Block left. If the current Stream has no Blocks left,
|
||
| 255 | * the next Stream with at least one Block is located and
|
||
| 256 | * the iterator will be made to point to the first Block of
|
||
| 257 | * that Stream.
|
||
| 258 | */
|
||
| 259 | |||
| 260 | LZMA_INDEX_ITER_NONEMPTY_BLOCK = 3
|
||
| 261 | /**<
|
||
| 262 | * \brief Get the next non-empty Block
|
||
| 263 | *
|
||
| 264 | * This is like LZMA_INDEX_ITER_BLOCK except that it will
|
||
| 265 | * skip Blocks whose Uncompressed Size is zero.
|
||
| 266 | */
|
||
| 267 | |||
| 268 | } lzma_index_iter_mode; |
||
| 269 | |||
| 270 | |||
| 271 | /**
|
||
| 272 | * \brief Calculate memory usage of lzma_index
|
||
| 273 | *
|
||
| 274 | * On disk, the size of the Index field depends on both the number of Records
|
||
| 275 | * stored and how big values the Records store (due to variable-length integer
|
||
| 276 | * encoding). When the Index is kept in lzma_index structure, the memory usage
|
||
| 277 | * depends only on the number of Records/Blocks stored in the Index(es), and
|
||
| 278 | * in case of concatenated lzma_indexes, the number of Streams. The size in
|
||
| 279 | * RAM is almost always significantly bigger than in the encoded form on disk.
|
||
| 280 | *
|
||
| 281 | * This function calculates an approximate amount of memory needed hold
|
||
| 282 | * the given number of Streams and Blocks in lzma_index structure. This
|
||
| 283 | * value may vary between CPU architectures and also between liblzma versions
|
||
| 284 | * if the internal implementation is modified.
|
||
| 285 | */
|
||
| 286 | extern LZMA_API(uint64_t) lzma_index_memusage(
|
||
| 287 | lzma_vli streams, lzma_vli blocks) lzma_nothrow; |
||
| 288 | |||
| 289 | |||
| 290 | /**
|
||
| 291 | * \brief Calculate the memory usage of an existing lzma_index
|
||
| 292 | *
|
||
| 293 | * This is a shorthand for lzma_index_memusage(lzma_index_stream_count(i),
|
||
| 294 | * lzma_index_block_count(i)).
|
||
| 295 | */
|
||
| 296 | extern LZMA_API(uint64_t) lzma_index_memused(const lzma_index *i) |
||
| 297 | lzma_nothrow; |
||
| 298 | |||
| 299 | |||
| 300 | /**
|
||
| 301 | * \brief Allocate and initialize a new lzma_index structure
|
||
| 302 | *
|
||
| 303 | * \return On success, a pointer to an empty initialized lzma_index is
|
||
| 304 | * returned. If allocation fails, NULL is returned.
|
||
| 305 | */
|
||
| 306 | extern LZMA_API(lzma_index *) lzma_index_init(const lzma_allocator *allocator) |
||
| 307 | lzma_nothrow; |
||
| 308 | |||
| 309 | |||
| 310 | /**
|
||
| 311 | * \brief Deallocate lzma_index
|
||
| 312 | *
|
||
| 313 | * If i is NULL, this does nothing.
|
||
| 314 | */
|
||
| 315 | extern LZMA_API(void) lzma_index_end( |
||
| 316 | lzma_index *i, const lzma_allocator *allocator) lzma_nothrow;
|
||
| 317 | |||
| 318 | |||
| 319 | /**
|
||
| 320 | * \brief Add a new Block to lzma_index
|
||
| 321 | *
|
||
| 322 | * \param i Pointer to a lzma_index structure
|
||
| 323 | * \param allocator Pointer to lzma_allocator, or NULL to
|
||
| 324 | * use malloc()
|
||
| 325 | * \param unpadded_size Unpadded Size of a Block. This can be
|
||
| 326 | * calculated with lzma_block_unpadded_size()
|
||
| 327 | * after encoding or decoding the Block.
|
||
| 328 | * \param uncompressed_size Uncompressed Size of a Block. This can be
|
||
| 329 | * taken directly from lzma_block structure
|
||
| 330 | * after encoding or decoding the Block.
|
||
| 331 | *
|
||
| 332 | * Appending a new Block does not invalidate iterators. For example,
|
||
| 333 | * if an iterator was pointing to the end of the lzma_index, after
|
||
| 334 | * lzma_index_append() it is possible to read the next Block with
|
||
| 335 | * an existing iterator.
|
||
| 336 | *
|
||
| 337 | * \return - LZMA_OK
|
||
| 338 | * - LZMA_MEM_ERROR
|
||
| 339 | * - LZMA_DATA_ERROR: Compressed or uncompressed size of the
|
||
| 340 | * Stream or size of the Index field would grow too big.
|
||
| 341 | * - LZMA_PROG_ERROR
|
||
| 342 | */
|
||
| 343 | extern LZMA_API(lzma_ret) lzma_index_append(
|
||
| 344 | lzma_index *i, const lzma_allocator *allocator,
|
||
| 345 | lzma_vli unpadded_size, lzma_vli uncompressed_size) |
||
| 346 | lzma_nothrow lzma_attr_warn_unused_result; |
||
| 347 | |||
| 348 | |||
| 349 | /**
|
||
| 350 | * \brief Set the Stream Flags
|
||
| 351 | *
|
||
| 352 | * Set the Stream Flags of the last (and typically the only) Stream
|
||
| 353 | * in lzma_index. This can be useful when reading information from the
|
||
| 354 | * lzma_index, because to decode Blocks, knowing the integrity check type
|
||
| 355 | * is needed.
|
||
| 356 | *
|
||
| 357 | * The given Stream Flags are copied into internal preallocated structure
|
||
| 358 | * in the lzma_index, thus the caller doesn't need to keep the *stream_flags
|
||
| 359 | * available after calling this function.
|
||
| 360 | *
|
||
| 361 | * \return - LZMA_OK
|
||
| 362 | * - LZMA_OPTIONS_ERROR: Unsupported stream_flags->version.
|
||
| 363 | * - LZMA_PROG_ERROR
|
||
| 364 | */
|
||
| 365 | extern LZMA_API(lzma_ret) lzma_index_stream_flags(
|
||
| 366 | lzma_index *i, const lzma_stream_flags *stream_flags)
|
||
| 367 | lzma_nothrow lzma_attr_warn_unused_result; |
||
| 368 | |||
| 369 | |||
| 370 | /**
|
||
| 371 | * \brief Get the types of integrity Checks
|
||
| 372 | *
|
||
| 373 | * If lzma_index_stream_flags() is used to set the Stream Flags for
|
||
| 374 | * every Stream, lzma_index_checks() can be used to get a bitmask to
|
||
| 375 | * indicate which Check types have been used. It can be useful e.g. if
|
||
| 376 | * showing the Check types to the user.
|
||
| 377 | *
|
||
| 378 | * The bitmask is 1 << check_id, e.g. CRC32 is 1 << 1 and SHA-256 is 1 << 10.
|
||
| 379 | */
|
||
| 380 | extern LZMA_API(uint32_t) lzma_index_checks(const lzma_index *i) |
||
| 381 | lzma_nothrow lzma_attr_pure; |
||
| 382 | |||
| 383 | |||
| 384 | /**
|
||
| 385 | * \brief Set the amount of Stream Padding
|
||
| 386 | *
|
||
| 387 | * Set the amount of Stream Padding of the last (and typically the only)
|
||
| 388 | * Stream in the lzma_index. This is needed when planning to do random-access
|
||
| 389 | * reading within multiple concatenated Streams.
|
||
| 390 | *
|
||
| 391 | * By default, the amount of Stream Padding is assumed to be zero bytes.
|
||
| 392 | *
|
||
| 393 | * \return - LZMA_OK
|
||
| 394 | * - LZMA_DATA_ERROR: The file size would grow too big.
|
||
| 395 | * - LZMA_PROG_ERROR
|
||
| 396 | */
|
||
| 397 | extern LZMA_API(lzma_ret) lzma_index_stream_padding(
|
||
| 398 | lzma_index *i, lzma_vli stream_padding) |
||
| 399 | lzma_nothrow lzma_attr_warn_unused_result; |
||
| 400 | |||
| 401 | |||
| 402 | /**
|
||
| 403 | * \brief Get the number of Streams
|
||
| 404 | */
|
||
| 405 | extern LZMA_API(lzma_vli) lzma_index_stream_count(const lzma_index *i) |
||
| 406 | lzma_nothrow lzma_attr_pure; |
||
| 407 | |||
| 408 | |||
| 409 | /**
|
||
| 410 | * \brief Get the number of Blocks
|
||
| 411 | *
|
||
| 412 | * This returns the total number of Blocks in lzma_index. To get number
|
||
| 413 | * of Blocks in individual Streams, use lzma_index_iter.
|
||
| 414 | */
|
||
| 415 | extern LZMA_API(lzma_vli) lzma_index_block_count(const lzma_index *i) |
||
| 416 | lzma_nothrow lzma_attr_pure; |
||
| 417 | |||
| 418 | |||
| 419 | /**
|
||
| 420 | * \brief Get the size of the Index field as bytes
|
||
| 421 | *
|
||
| 422 | * This is needed to verify the Backward Size field in the Stream Footer.
|
||
| 423 | */
|
||
| 424 | extern LZMA_API(lzma_vli) lzma_index_size(const lzma_index *i) |
||
| 425 | lzma_nothrow lzma_attr_pure; |
||
| 426 | |||
| 427 | |||
| 428 | /**
|
||
| 429 | * \brief Get the total size of the Stream
|
||
| 430 | *
|
||
| 431 | * If multiple lzma_indexes have been combined, this works as if the Blocks
|
||
| 432 | * were in a single Stream. This is useful if you are going to combine
|
||
| 433 | * Blocks from multiple Streams into a single new Stream.
|
||
| 434 | */
|
||
| 435 | extern LZMA_API(lzma_vli) lzma_index_stream_size(const lzma_index *i) |
||
| 436 | lzma_nothrow lzma_attr_pure; |
||
| 437 | |||
| 438 | |||
| 439 | /**
|
||
| 440 | * \brief Get the total size of the Blocks
|
||
| 441 | *
|
||
| 442 | * This doesn't include the Stream Header, Stream Footer, Stream Padding,
|
||
| 443 | * or Index fields.
|
||
| 444 | */
|
||
| 445 | extern LZMA_API(lzma_vli) lzma_index_total_size(const lzma_index *i) |
||
| 446 | lzma_nothrow lzma_attr_pure; |
||
| 447 | |||
| 448 | |||
| 449 | /**
|
||
| 450 | * \brief Get the total size of the file
|
||
| 451 | *
|
||
| 452 | * When no lzma_indexes have been combined with lzma_index_cat() and there is
|
||
| 453 | * no Stream Padding, this function is identical to lzma_index_stream_size().
|
||
| 454 | * If multiple lzma_indexes have been combined, this includes also the headers
|
||
| 455 | * of each separate Stream and the possible Stream Padding fields.
|
||
| 456 | */
|
||
| 457 | extern LZMA_API(lzma_vli) lzma_index_file_size(const lzma_index *i) |
||
| 458 | lzma_nothrow lzma_attr_pure; |
||
| 459 | |||
| 460 | |||
| 461 | /**
|
||
| 462 | * \brief Get the uncompressed size of the file
|
||
| 463 | */
|
||
| 464 | extern LZMA_API(lzma_vli) lzma_index_uncompressed_size(const lzma_index *i) |
||
| 465 | lzma_nothrow lzma_attr_pure; |
||
| 466 | |||
| 467 | |||
| 468 | /**
|
||
| 469 | * \brief Initialize an iterator
|
||
| 470 | *
|
||
| 471 | * \param iter Pointer to a lzma_index_iter structure
|
||
| 472 | * \param i lzma_index to which the iterator will be associated
|
||
| 473 | *
|
||
| 474 | * This function associates the iterator with the given lzma_index, and calls
|
||
| 475 | * lzma_index_iter_rewind() on the iterator.
|
||
| 476 | *
|
||
| 477 | * This function doesn't allocate any memory, thus there is no
|
||
| 478 | * lzma_index_iter_end(). The iterator is valid as long as the
|
||
| 479 | * associated lzma_index is valid, that is, until lzma_index_end() or
|
||
| 480 | * using it as source in lzma_index_cat(). Specifically, lzma_index doesn't
|
||
| 481 | * become invalid if new Blocks are added to it with lzma_index_append() or
|
||
| 482 | * if it is used as the destination in lzma_index_cat().
|
||
| 483 | *
|
||
| 484 | * It is safe to make copies of an initialized lzma_index_iter, for example,
|
||
| 485 | * to easily restart reading at some particular position.
|
||
| 486 | */
|
||
| 487 | extern LZMA_API(void) lzma_index_iter_init( |
||
| 488 | lzma_index_iter *iter, const lzma_index *i) lzma_nothrow;
|
||
| 489 | |||
| 490 | |||
| 491 | /**
|
||
| 492 | * \brief Rewind the iterator
|
||
| 493 | *
|
||
| 494 | * Rewind the iterator so that next call to lzma_index_iter_next() will
|
||
| 495 | * return the first Block or Stream.
|
||
| 496 | */
|
||
| 497 | extern LZMA_API(void) lzma_index_iter_rewind(lzma_index_iter *iter) |
||
| 498 | lzma_nothrow; |
||
| 499 | |||
| 500 | |||
| 501 | /**
|
||
| 502 | * \brief Get the next Block or Stream
|
||
| 503 | *
|
||
| 504 | * \param iter Iterator initialized with lzma_index_iter_init()
|
||
| 505 | * \param mode Specify what kind of information the caller wants
|
||
| 506 | * to get. See lzma_index_iter_mode for details.
|
||
| 507 | *
|
||
| 508 | * \return If next Block or Stream matching the mode was found, *iter
|
||
| 509 | * is updated and this function returns false. If no Block or
|
||
| 510 | * Stream matching the mode is found, *iter is not modified
|
||
| 511 | * and this function returns true. If mode is set to an unknown
|
||
| 512 | * value, *iter is not modified and this function returns true.
|
||
| 513 | */
|
||
| 514 | extern LZMA_API(lzma_bool) lzma_index_iter_next(
|
||
| 515 | lzma_index_iter *iter, lzma_index_iter_mode mode) |
||
| 516 | lzma_nothrow lzma_attr_warn_unused_result; |
||
| 517 | |||
| 518 | |||
| 519 | /**
|
||
| 520 | * \brief Locate a Block
|
||
| 521 | *
|
||
| 522 | * If it is possible to seek in the .xz file, it is possible to parse
|
||
| 523 | * the Index field(s) and use lzma_index_iter_locate() to do random-access
|
||
| 524 | * reading with granularity of Block size.
|
||
| 525 | *
|
||
| 526 | * \param iter Iterator that was earlier initialized with
|
||
| 527 | * lzma_index_iter_init().
|
||
| 528 | * \param target Uncompressed target offset which the caller would
|
||
| 529 | * like to locate from the Stream
|
||
| 530 | *
|
||
| 531 | * If the target is smaller than the uncompressed size of the Stream (can be
|
||
| 532 | * checked with lzma_index_uncompressed_size()):
|
||
| 533 | * - Information about the Stream and Block containing the requested
|
||
| 534 | * uncompressed offset is stored into *iter.
|
||
| 535 | * - Internal state of the iterator is adjusted so that
|
||
| 536 | * lzma_index_iter_next() can be used to read subsequent Blocks or Streams.
|
||
| 537 | * - This function returns false.
|
||
| 538 | *
|
||
| 539 | * If target is greater than the uncompressed size of the Stream, *iter
|
||
| 540 | * is not modified, and this function returns true.
|
||
| 541 | */
|
||
| 542 | extern LZMA_API(lzma_bool) lzma_index_iter_locate(
|
||
| 543 | lzma_index_iter *iter, lzma_vli target) lzma_nothrow; |
||
| 544 | |||
| 545 | |||
| 546 | /**
|
||
| 547 | * \brief Concatenate lzma_indexes
|
||
| 548 | *
|
||
| 549 | * Concatenating lzma_indexes is useful when doing random-access reading in
|
||
| 550 | * multi-Stream .xz file, or when combining multiple Streams into single
|
||
| 551 | * Stream.
|
||
| 552 | *
|
||
| 553 | * \param dest lzma_index after which src is appended
|
||
| 554 | * \param src lzma_index to be appended after dest. If this
|
||
| 555 | * function succeeds, the memory allocated for src
|
||
| 556 | * is freed or moved to be part of dest, and all
|
||
| 557 | * iterators pointing to src will become invalid.
|
||
| 558 | * \param allocator Custom memory allocator; can be NULL to use
|
||
| 559 | * malloc() and free().
|
||
| 560 | *
|
||
| 561 | * \return - LZMA_OK: lzma_indexes were concatenated successfully.
|
||
| 562 | * src is now a dangling pointer.
|
||
| 563 | * - LZMA_DATA_ERROR: *dest would grow too big.
|
||
| 564 | * - LZMA_MEM_ERROR
|
||
| 565 | * - LZMA_PROG_ERROR
|
||
| 566 | */
|
||
| 567 | extern LZMA_API(lzma_ret) lzma_index_cat(lzma_index *dest, lzma_index *src,
|
||
| 568 | const lzma_allocator *allocator)
|
||
| 569 | lzma_nothrow lzma_attr_warn_unused_result; |
||
| 570 | |||
| 571 | |||
| 572 | /**
|
||
| 573 | * \brief Duplicate lzma_index
|
||
| 574 | *
|
||
| 575 | * \return A copy of the lzma_index, or NULL if memory allocation failed.
|
||
| 576 | */
|
||
| 577 | extern LZMA_API(lzma_index *) lzma_index_dup(
|
||
| 578 | const lzma_index *i, const lzma_allocator *allocator) |
||
| 579 | lzma_nothrow lzma_attr_warn_unused_result; |
||
| 580 | |||
| 581 | |||
| 582 | /**
|
||
| 583 | * \brief Initialize .xz Index encoder
|
||
| 584 | *
|
||
| 585 | * \param strm Pointer to properly prepared lzma_stream
|
||
| 586 | * \param i Pointer to lzma_index which should be encoded.
|
||
| 587 | *
|
||
| 588 | * The valid `action' values for lzma_code() are LZMA_RUN and LZMA_FINISH.
|
||
| 589 | * It is enough to use only one of them (you can choose freely; use LZMA_RUN
|
||
| 590 | * to support liblzma versions older than 5.0.0).
|
||
| 591 | *
|
||
| 592 | * \return - LZMA_OK: Initialization succeeded, continue with lzma_code().
|
||
| 593 | * - LZMA_MEM_ERROR
|
||
| 594 | * - LZMA_PROG_ERROR
|
||
| 595 | */
|
||
| 596 | extern LZMA_API(lzma_ret) lzma_index_encoder(
|
||
| 597 | lzma_stream *strm, const lzma_index *i)
|
||
| 598 | lzma_nothrow lzma_attr_warn_unused_result; |
||
| 599 | |||
| 600 | |||
| 601 | /**
|
||
| 602 | * \brief Initialize .xz Index decoder
|
||
| 603 | *
|
||
| 604 | * \param strm Pointer to properly prepared lzma_stream
|
||
| 605 | * \param i The decoded Index will be made available via
|
||
| 606 | * this pointer. Initially this function will
|
||
| 607 | * set *i to NULL (the old value is ignored). If
|
||
| 608 | * decoding succeeds (lzma_code() returns
|
||
| 609 | * LZMA_STREAM_END), *i will be set to point
|
||
| 610 | * to a new lzma_index, which the application
|
||
| 611 | * has to later free with lzma_index_end().
|
||
| 612 | * \param memlimit How much memory the resulting lzma_index is
|
||
| 613 | * allowed to require.
|
||
| 614 | *
|
||
| 615 | * The valid `action' values for lzma_code() are LZMA_RUN and LZMA_FINISH.
|
||
| 616 | * It is enough to use only one of them (you can choose freely; use LZMA_RUN
|
||
| 617 | * to support liblzma versions older than 5.0.0).
|
||
| 618 | *
|
||
| 619 | * \return - LZMA_OK: Initialization succeeded, continue with lzma_code().
|
||
| 620 | * - LZMA_MEM_ERROR
|
||
| 621 | * - LZMA_MEMLIMIT_ERROR
|
||
| 622 | * - LZMA_PROG_ERROR
|
||
| 623 | */
|
||
| 624 | extern LZMA_API(lzma_ret) lzma_index_decoder(
|
||
| 625 | lzma_stream *strm, lzma_index **i, uint64_t memlimit) |
||
| 626 | lzma_nothrow lzma_attr_warn_unused_result; |
||
| 627 | |||
| 628 | |||
| 629 | /**
|
||
| 630 | * \brief Single-call .xz Index encoder
|
||
| 631 | *
|
||
| 632 | * \param i lzma_index to be encoded
|
||
| 633 | * \param out Beginning of the output buffer
|
||
| 634 | * \param out_pos The next byte will be written to out[*out_pos].
|
||
| 635 | * *out_pos is updated only if encoding succeeds.
|
||
| 636 | * \param out_size Size of the out buffer; the first byte into
|
||
| 637 | * which no data is written to is out[out_size].
|
||
| 638 | *
|
||
| 639 | * \return - LZMA_OK: Encoding was successful.
|
||
| 640 | * - LZMA_BUF_ERROR: Output buffer is too small. Use
|
||
| 641 | * lzma_index_size() to find out how much output
|
||
| 642 | * space is needed.
|
||
| 643 | * - LZMA_PROG_ERROR
|
||
| 644 | *
|
||
| 645 | * \note This function doesn't take allocator argument since all
|
||
| 646 | * the internal data is allocated on stack.
|
||
| 647 | */
|
||
| 648 | extern LZMA_API(lzma_ret) lzma_index_buffer_encode(const lzma_index *i, |
||
| 649 | uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow; |
||
| 650 | |||
| 651 | |||
| 652 | /**
|
||
| 653 | * \brief Single-call .xz Index decoder
|
||
| 654 | *
|
||
| 655 | * \param i If decoding succeeds, *i will point to a new
|
||
| 656 | * lzma_index, which the application has to
|
||
| 657 | * later free with lzma_index_end(). If an error
|
||
| 658 | * occurs, *i will be NULL. The old value of *i
|
||
| 659 | * is always ignored and thus doesn't need to be
|
||
| 660 | * initialized by the caller.
|
||
| 661 | * \param memlimit Pointer to how much memory the resulting
|
||
| 662 | * lzma_index is allowed to require. The value
|
||
| 663 | * pointed by this pointer is modified if and only
|
||
| 664 | * if LZMA_MEMLIMIT_ERROR is returned.
|
||
| 665 | * \param allocator Pointer to lzma_allocator, or NULL to use malloc()
|
||
| 666 | * \param in Beginning of the input buffer
|
||
| 667 | * \param in_pos The next byte will be read from in[*in_pos].
|
||
| 668 | * *in_pos is updated only if decoding succeeds.
|
||
| 669 | * \param in_size Size of the input buffer; the first byte that
|
||
| 670 | * won't be read is in[in_size].
|
||
| 671 | *
|
||
| 672 | * \return - LZMA_OK: Decoding was successful.
|
||
| 673 | * - LZMA_MEM_ERROR
|
||
| 674 | * - LZMA_MEMLIMIT_ERROR: Memory usage limit was reached.
|
||
| 675 | * The minimum required memlimit value was stored to *memlimit.
|
||
| 676 | * - LZMA_DATA_ERROR
|
||
| 677 | * - LZMA_PROG_ERROR
|
||
| 678 | */
|
||
| 679 | extern LZMA_API(lzma_ret) lzma_index_buffer_decode(lzma_index **i,
|
||
| 680 | uint64_t *memlimit, const lzma_allocator *allocator,
|
||
| 681 | const uint8_t *in, size_t *in_pos, size_t in_size)
|
||
| 682 | lzma_nothrow; |