aboutsummaryrefslogtreecommitdiff
path: root/src/liblzma/api/lzma/index.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/liblzma/api/lzma/index.h')
-rw-r--r--src/liblzma/api/lzma/index.h204
1 files changed, 176 insertions, 28 deletions
diff --git a/src/liblzma/api/lzma/index.h b/src/liblzma/api/lzma/index.h
index 7e59c4b3..13cddf47 100644
--- a/src/liblzma/api/lzma/index.h
+++ b/src/liblzma/api/lzma/index.h
@@ -22,63 +22,211 @@
/**
- * \brief
- *
- * FIXME desc
+ * \brief Opaque data type to hold the Index
*/
typedef struct lzma_index_s lzma_index;
-struct lzma_index_s {
+
+
+/**
+ * \brief Index Record and its location
+ */
+typedef struct {
/**
- * \brief Total Size of the Block
- *
- * This includes Block Header, Compressed Data, and Block Footer.
+ * Total Size of a Block.
*/
lzma_vli total_size;
/**
- * \brief Uncompressed Size of the Block
+ * Uncompressed Size of a Block
*/
lzma_vli uncompressed_size;
/**
- * \brief Pointer to the next Index Record
- *
- * This is NULL on the last Index Record.
+ * Offset of the first byte of a Block relative to the beginning
+ * of the Stream, or if there are multiple Indexes combined,
+ * relative to the beginning of the first Stream.
*/
- lzma_index *next;
-};
+ lzma_vli stream_offset;
+
+ /**
+ * Uncompressed offset
+ */
+ lzma_vli uncompressed_offset;
+
+} lzma_index_record;
/**
- * \brief Duplicates an Index list
+ * \brief Allocate and initialize a new lzma_index structure
+ *
+ * If i is NULL, a new lzma_index structure is allocated, initialized,
+ * and a pointer to it returned. If allocation fails, NULL is returned.
*
- * \return A copy of the Index list, or NULL if memory allocation
- * failed or the original Index was empty.
+ * If i is non-NULL, it is reinitialized and the same pointer returned.
+ * In this case, return value cannot be NULL or a different pointer than
+ * the i given as argument.
*/
-extern lzma_index *lzma_index_dup(
- const lzma_index *index, lzma_allocator *allocator);
+extern lzma_index *lzma_index_init(lzma_index *i, lzma_allocator *allocator);
+
+
+/**
+ * \brief Deallocate the Index
+ */
+extern void lzma_index_end(lzma_index *i, lzma_allocator *allocator);
/**
- * \brief Frees an Index list
+ * \brief Add a new Record to an Index
*
- * All Index Recors in the list are freed. This function is convenient when
- * getting rid of lzma_metadata structures containing an Index.
+ * \param index Pointer to a lzma_index structure
+ * \param total_size Total Size of a Block
+ * \param uncompressed_size Uncompressed Size of a Block, or
+ * LZMA_VLI_VALUE_UNKNOWN to indicate padding.
+ *
+ * Appending a new Record does not affect the read position.
+ *
+ * \return - LZMA_OK
+ * - LZMA_DATA_ERROR: Compressed or uncompressed size of the
+ * Stream or size of the Index field would grow too big.
+ * - LZMA_PROG_ERROR
*/
-extern void lzma_index_free(lzma_index *index, lzma_allocator *allocator);
+extern lzma_ret lzma_index_append(lzma_index *i, lzma_allocator *allocator,
+ lzma_vli total_size, lzma_vli uncompressed_size);
/**
- * \brief Calculates information about the Index
+ * \brief Get the number of Records
+ */
+extern lzma_vli lzma_index_count(const lzma_index *i);
+
+
+/**
+ * \brief Get the size of the Index field as bytes
+ *
+ * This is needed to verify the Index Size field from the Stream Footer.
+ */
+extern lzma_vli lzma_index_size(const lzma_index *i);
+
+
+/**
+ * \brief Get the total size of the Blocks
+ *
+ * This doesn't include the Stream Header, Stream Footer, Stream Padding,
+ * or Index fields.
+ */
+extern lzma_vli lzma_index_total_size(const lzma_index *i);
+
+
+/**
+ * \brief Get the total size of the Stream
+ *
+ * If multiple Indexes have been combined, this works as if the Blocks
+ * were in a single Stream.
+ */
+extern lzma_vli lzma_index_stream_size(const lzma_index *i);
+
+
+/**
+ * \brief Get the total size of the file
*
- * \return LZMA_OK on success, LZMA_PROG_ERROR on error. FIXME
+ * When no Indexes have been combined with lzma_index_cat(), this function is
+ * identical to lzma_index_stream_size(). If multiple Indexes have been
+ * combined, this includes also the possible Stream Padding fields.
+ */
+extern lzma_vli lzma_index_file_size(const lzma_index *i);
+
+
+/**
+ * \brief Get the uncompressed size of the Stream
*/
-extern lzma_ret lzma_index_count(const lzma_index *index, size_t *count,
- lzma_vli *lzma_restrict total_size,
- lzma_vli *lzma_restrict uncompressed_size);
+extern lzma_vli lzma_index_uncompressed_size(const lzma_index *i);
+
+
+/**
+ * \brief Get the next Record from the Index
+ */
+extern lzma_bool lzma_index_read(lzma_index *i, lzma_index_record *record);
+
+
+/**
+ * \brief Rewind the Index
+ *
+ * Rewind the Index so that next call to lzma_index_read() will return the
+ * first Record.
+ */
+extern void lzma_index_rewind(lzma_index *i);
+
+
+/**
+ * \brief Locate a Record
+ *
+ * When the Index is available, it is possible to do random-access reading
+ * with granularity of Block size.
+ *
+ * \param i Pointer to lzma_index structure
+ * \param record Pointer to a structure to hold the search results
+ * \param target Uncompressed target offset
+ *
+ * If the target is smaller than the uncompressed size of the Stream (can be
+ * checked with lzma_index_uncompressed_size()):
+ * - Information about the Record containing the requested uncompressed
+ * offset is stored into *record.
+ * - Read offset will be adjusted so that calling lzma_index_read() can be
+ * used to read subsequent Records.
+ * - This function returns false.
+ *
+ * If target is greater than the uncompressed size of the Stream, *record
+ * and the read position are not modified, and this function returns true.
+ */
+extern lzma_bool lzma_index_locate(
+ lzma_index *i, lzma_index_record *record, lzma_vli target);
+
+
+/**
+ * \brief Concatenate Indexes of two Streams
+ *
+ *
+ *
+ * \param dest Destination Index after which src is appended Source
+ * \param src Index. The memory allocated for this is either moved
+ * to be part of *dest or freed iff the function call
+ * succeeds, and src will be an invalid pointer.
+ * \param allocator Custom memory allocator; can be NULL to use
+ * malloc() and free().
+ * \param padding Size of the Stream Padding field between Streams.
+ *
+ * \return - LZMA_OK: Indexes concatenated successfully.
+ * - LZMA_DATA_ERROR: *dest would grow too big.
+ * - LZMA_MEM_ERROR
+ * - LZMA_PROG_ERROR
+ */
+extern lzma_ret lzma_index_cat(lzma_index *lzma_restrict dest,
+ lzma_index *lzma_restrict src,
+ lzma_allocator *allocator, lzma_vli padding);
+
+
+/**
+ * \brief Duplicates an Index list
+ *
+ * \return A copy of the Index, or NULL if memory allocation failed.
+ */
+extern lzma_index *lzma_index_dup(
+ const lzma_index *i, lzma_allocator *allocator);
/**
* \brief Compares if two Index lists are identical
*/
-extern lzma_bool lzma_index_is_equal(const lzma_index *a, const lzma_index *b);
+extern lzma_bool lzma_index_equal(const lzma_index *a, const lzma_index *b);
+
+
+/**
+ * \brief Initializes Index encoder
+ */
+extern lzma_ret lzma_index_encoder(lzma_stream *strm, lzma_index *i);
+
+
+/**
+ * \brief Initializes Index decoder
+ */
+extern lzma_ret lzma_index_decoder(lzma_stream *strm, lzma_index **i);