209 lines
7.2 KiB
C
209 lines
7.2 KiB
C
|
// The contents from this file are from a proposed API that is not yet
|
||
|
|
// implemented in upstream liblzma.
|
||
|
|
|
||
|
|
#ifndef INDEX_PARSER_H
|
||
|
|
#define INDEX_PARSER_H
|
||
|
|
|
||
|
|
#include <stdint.h>
|
||
|
|
#include <stdlib.h>
|
||
|
|
#include <lzma.h>
|
||
|
|
|
||
|
|
namespace lzma {
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \brief Internal data structure
|
||
|
|
*
|
||
|
|
* The contents of this structure is not visible outside the library.
|
||
|
|
*/
|
||
|
|
typedef struct lzma_index_parser_internal_s lzma_index_parser_internal;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \brief Reading the indexes of an .xz file
|
||
|
|
*
|
||
|
|
* The lzma_index_parser_data data structure is passed to
|
||
|
|
* lzma_parse_indexes_from_file(), which can be used to retrieve the index
|
||
|
|
* information for a given .xz file.
|
||
|
|
*
|
||
|
|
* It should be initialized with LZMA_INDEX_PARSER_DATA_INIT,
|
||
|
|
* and, minimally, the file_size and read_callback() members need to be set.
|
||
|
|
*
|
||
|
|
* The allocation of internals happens transparently upon usage and does not
|
||
|
|
* need to be taken care of.
|
||
|
|
* In the case of an error, lzma_parse_indexes_from_file() performs all
|
||
|
|
* necessary cleanup.
|
||
|
|
* In the case of success, the index member will be set and needs to be
|
||
|
|
* freed using lzma_index_end after the caller is done with it. If a custom
|
||
|
|
* allocator was set on this struct, it needs to be used for freeing the
|
||
|
|
* resulting index, too.
|
||
|
|
*
|
||
|
|
* Reading the data from the underlying file may happen synchronously or
|
||
|
|
* asynchronously, see the description of the read_callback().
|
||
|
|
*/
|
||
|
|
typedef struct {
|
||
|
|
/**
|
||
|
|
* \brief Combined Index of all Streams in the file
|
||
|
|
*
|
||
|
|
* This will be set to an lzma_index * when parsing the file was
|
||
|
|
* successful, as indicated by a LZMA_STREAM_END return status.
|
||
|
|
*/
|
||
|
|
lzma_index *index;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \brief Total amount of Stream Padding
|
||
|
|
*
|
||
|
|
* This will be set when the file was successfully read.
|
||
|
|
*/
|
||
|
|
size_t stream_padding;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \brief Callback for reading data from the input file
|
||
|
|
*
|
||
|
|
* This member needs to be set to a function that provides a slice of
|
||
|
|
* the input file.
|
||
|
|
*
|
||
|
|
* The opaque pointer will have the same value as the opaque pointer
|
||
|
|
* set on this struct.
|
||
|
|
*
|
||
|
|
* When being invoked, it should read count bytes from the underlying
|
||
|
|
* file, starting at the specified offset, into buf.
|
||
|
|
* The return value may be -1, in which case
|
||
|
|
* lzma_parse_indexes_from_file() will return with LZMA_DATA_ERROR.
|
||
|
|
* Otherwise, the number of read bytes should be returned. If this is
|
||
|
|
* not the number of requested bytes, it will be assumed that the file
|
||
|
|
* was truncated, and lzma_parse_indexes_from_file() will fail with
|
||
|
|
* LZMA_DATA_ERROR.
|
||
|
|
*
|
||
|
|
* It is possible to perform the underlying I/O operations in an
|
||
|
|
* asynchronous manner. To do so, set the async flag on this struct
|
||
|
|
* to true. After read_callback() is invoked,
|
||
|
|
* lzma_parse_indexes_from_file() will return immediately with
|
||
|
|
* LZMA_OK (unless the read_callback() return value indicates failure),
|
||
|
|
* and you are expected to call lzma_parse_indexes_from_file() with
|
||
|
|
* the same struct as soon as the buffer has been filled.
|
||
|
|
*
|
||
|
|
* If asynchronous reading is used and the underlying read operation
|
||
|
|
* fails, you should set file_size to SIZE_MAX and call
|
||
|
|
* lzma_parse_indexes_from_file() to trigger an error clean up all
|
||
|
|
* remaining internal state.
|
||
|
|
*
|
||
|
|
* You should not perform any operations on this structure until
|
||
|
|
* the data has been read in any case.
|
||
|
|
*
|
||
|
|
* This function is modelled after pread(2), which is a available on
|
||
|
|
* some platforms and can be easily wrapped to be used here.
|
||
|
|
*/
|
||
|
|
int64_t (LZMA_API_CALL *read_callback)(void *opaque,
|
||
|
|
uint8_t *buf,
|
||
|
|
size_t count,
|
||
|
|
int64_t offset);
|
||
|
|
|
||
|
|
/// Opaque pointer that is passed to read_callback.
|
||
|
|
void *opaque;
|
||
|
|
|
||
|
|
/// Whether to return after calling read_callback and wait for
|
||
|
|
/// another call. Defaults to synchronous operations.
|
||
|
|
lzma_bool async;
|
||
|
|
|
||
|
|
/** \brief Callback for reading data from the input file
|
||
|
|
*
|
||
|
|
* This needs to be set to the size of the input file before all
|
||
|
|
* other operations. If this is set to SIZE_MAX, the parser will
|
||
|
|
* fail with LZMA_OPTIONS_ERROR. This can be used to clean up
|
||
|
|
* after a failed asynchronous read_callback().
|
||
|
|
*
|
||
|
|
* On error, this will be set to SIZE_MAX.
|
||
|
|
*/
|
||
|
|
size_t file_size;
|
||
|
|
|
||
|
|
/** \brief Memory limit for decoding the indexes.
|
||
|
|
*
|
||
|
|
* Set a memory limit for decoding. Default to UINT64_MAX for no limit.
|
||
|
|
* If this is set too low to allocate the internal data structure
|
||
|
|
* that is minimally required for parsing, this will be set to 0.
|
||
|
|
* If this is set too low to parse the underlying .xz file,
|
||
|
|
* this will be set to the amount of memory that would have
|
||
|
|
* been necessary for parsing the file.
|
||
|
|
*/
|
||
|
|
uint64_t memlimit;
|
||
|
|
|
||
|
|
/// Message that may be set when additional information is available
|
||
|
|
/// on error.
|
||
|
|
const char *message;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \brief Custom memory allocation functions
|
||
|
|
*
|
||
|
|
* In most cases this is NULL which makes liblzma use
|
||
|
|
* the standard malloc() and free().
|
||
|
|
*/
|
||
|
|
const lzma_allocator *allocator;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \brief Data which is internal to the index parser.
|
||
|
|
*
|
||
|
|
* Do not touch. You can check whether this is NULL to see if this
|
||
|
|
* structure currently holds external resources, not counting the
|
||
|
|
* possible index member that is set on success.
|
||
|
|
*/
|
||
|
|
lzma_index_parser_internal* internal;
|
||
|
|
|
||
|
|
/*
|
||
|
|
* Reserved space to allow possible future extensions without
|
||
|
|
* breaking the ABI. Excluding the initialization of this structure,
|
||
|
|
* you should not touch these, because the names of these variables
|
||
|
|
* may change.
|
||
|
|
*/
|
||
|
|
void *reserved_ptr1;
|
||
|
|
void *reserved_ptr2;
|
||
|
|
void *reserved_ptr3;
|
||
|
|
void *reserved_ptr4;
|
||
|
|
uint64_t reserved_int1;
|
||
|
|
uint64_t reserved_int2;
|
||
|
|
size_t reserved_int3;
|
||
|
|
size_t reserved_int4;
|
||
|
|
lzma_reserved_enum reserved_enum1;
|
||
|
|
lzma_reserved_enum reserved_enum2;
|
||
|
|
} lzma_index_parser_data;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \brief Initialization for lzma_index_parser_data
|
||
|
|
*
|
||
|
|
* When you declare an instance of lzma_index_parser_data, you should
|
||
|
|
* immediately initialize it to this value:
|
||
|
|
*
|
||
|
|
* lzma_index_parser_data strm = LZMA_INDEX_PARSER_DATA_INIT;
|
||
|
|
*
|
||
|
|
* Anything which applies for LZMA_STREAM_INIT applies here, too.
|
||
|
|
*/
|
||
|
|
#define LZMA_INDEX_PARSER_DATA_INIT \
|
||
|
|
{ NULL, 0, NULL, NULL, 0, 0, 0, NULL, NULL, NULL, \
|
||
|
|
NULL, NULL, NULL, NULL, 0, 0, 0, 0, \
|
||
|
|
LZMA_RESERVED_ENUM, LZMA_RESERVED_ENUM }
|
||
|
|
|
||
|
|
/** \brief Parse the Index(es) from the given .xz file
|
||
|
|
*
|
||
|
|
* Read metadata from the underlying file.
|
||
|
|
* The info pointer should refer to a lzma_index_parser_data struct that
|
||
|
|
* has been initialized using LZMA_INDEX_PARSER_DATA_INIT.
|
||
|
|
*
|
||
|
|
* This will call info->read_callback() multiple times to read parts of the
|
||
|
|
* underlying .xz file and, upon success, fill info->index with an
|
||
|
|
* lzma_index pointer that contains metadata for the whole file, accumulated
|
||
|
|
* across multiple streams.
|
||
|
|
*
|
||
|
|
* \param info Pointer to a lzma_index_parser_data structure.
|
||
|
|
*
|
||
|
|
* \return On success, LZMA_STREAM_END is returned.
|
||
|
|
* On error, another value is returned, and info->message may
|
||
|
|
* be set to provide additional information.
|
||
|
|
* If info->async is set, LZMA_OK may be returned to indicate
|
||
|
|
* that another call to lzma_parse_indexes_from_file() should be
|
||
|
|
* performed after the data has been read.
|
||
|
|
*/
|
||
|
|
extern lzma_ret
|
||
|
|
my_lzma_parse_indexes_from_file(lzma_index_parser_data *info);
|
||
|
|
|
||
|
|
}
|
||
|
|
|
||
|
|
#endif
|