Move declarations for sqfs_xattr_reader_t to a seperate header

Signed-off-by: David Oberhollenzer <david.oberhollenzer@sigma-star.at>

2 files changed, 202 insertions, 164 deletions

diff --git a/include/sqfs/xattr.h b/include/sqfs/xattr.h
index e4a3efa..654fe9c 100644
--- a/include/sqfs/xattr.h
+++ b/include/sqfs/xattr.h
@@ -25,8 +25,7 @@
 /**
  * @file xattr.h
  *
- * @brief Contains on-disk data structures for storing extended attributes and
- *        declarations for the @ref sqfs_xattr_reader_t.
+ * @brief Contains on-disk data structures for storing extended attributes.
  */
 
 /**
@@ -149,39 +148,6 @@ struct sqfs_xattr_id_table_t {
 	sqfs_u64 locations[];
 };
 
-/**
- * @struct sqfs_xattr_reader_t
- *
- * @brief Abstracts read access to extended attributes in a SquashFS filesystem
- *
- * SquashFS stores extended attributes using multiple levels of indirection.
- * First of all, the key-value pairs of each inode (that has extended
- * attributes) are deduplicated and stored consecutively in meta data blocks.
- * Furthermore, a value can be stored out-of-band, i.e. it holds a reference to
- * another location from which the value has to be read.
- *
- * For each unique set of key-value pairs, a descriptor object is generated
- * that holds the location of the first pair, the number of pairs and the total
- * size used on disk. The array of descriptor objects is stored in multiple
- * meta data blocks. Each inode that has extended attributes holds a 32 bit
- * index into the descriptor array.
- *
- * The third layer of indirection is yet another table that points to the
- * locations of the previous two tables. Its location is in turn stored in
- * the super block.
- *
- * The sqfs_xattr_reader_t data structure takes care of the low level details
- * of loading and parsing the data.
- *
- * After creating an instance using @ref sqfs_xattr_reader_create, simply call
- * @ref sqfs_xattr_reader_load_locations to load and parse all of the location
- * tables. Then use @ref sqfs_xattr_reader_get_desc to resolve a 32 bit index
- * from an inode to a descriptor structure. Use @ref sqfs_xattr_reader_seek_kv
- * to point the reader to the start of the key-value pairs and the call
- * @ref sqfs_xattr_reader_read_key and @ref sqfs_xattr_reader_read_value
- * consecutively to read and decode each key-value pair.
- */
-
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -233,135 +199,6 @@ SQFS_API int sqfs_get_xattr_prefix_id(const char *key);
  */
 SQFS_API bool sqfs_has_xattr(const char *key);
 
-/**
- * @brief Load the locations of the xattr meta data blocks into memory
- *
- * @memberof sqfs_xattr_reader_t
- *
- * This function must be called explicitly after an xattr reader has been
- * created to load the actual location table from disk.
- *
- * @return Zero on success, a negative @ref E_SQFS_ERROR value on failure.
- */
-SQFS_API int sqfs_xattr_reader_load_locations(sqfs_xattr_reader_t *xr);
-
-/**
- * @brief Destroy an xattr reader and free all memory used by it
- *
- * @memberof sqfs_xattr_reader_t
- *
- * @param xr A pointer to an xattr reader instance
- */
-SQFS_API void sqfs_xattr_reader_destroy(sqfs_xattr_reader_t *xr);
-
-/**
- * @brief Create an xattr reader
- *
- * @memberof sqfs_xattr_reader_t
- *
- * This function creates an object that abstracts away read only access to
- * the extended attributes in a SquashFS filesystem.
- *
- * After creating a reader and before using it, call
- * @ref sqfs_xattr_reader_load_locations to load and parse the location
- * information required to look up xattr key-value pairs.
- *
- * All pointers passed to this function are stored internally for later use.
- * Do not destroy any of the pointed to objects before destroying the xattr
- * reader.
- *
- * @param file A pointer to a file object that contains the SquashFS filesystem
- * @param super A pointer to the SquashFS super block required to find the
- *              location tables.
- * @param cmp A pointer to a compressor used to uncompress the loaded meta data
- *            blocks.
- *
- * @return A pointer to a new xattr reader instance on success, NULL on
- *         allocation failure.
- */
-SQFS_API sqfs_xattr_reader_t *sqfs_xattr_reader_create(sqfs_file_t *file,
-						       sqfs_super_t *super,
-						       sqfs_compressor_t *cmp);
-
-/**
- * @brief Resolve an xattr index from an inode to an xattr description
- *
- * @memberof sqfs_xattr_reader_t
- *
- * This function takes an xattr index from an extended inode type and resolves
- * it to a descriptor that points to location of the key-value pairs and
- * indicates how many key-value pairs to read from there.
- *
- * @param xr A pointer to an xattr reader instance
- * @param idx The xattr index to resolve
- * @param desc Used to return the description
- *
- * @return Zero on success, a negative @ref E_SQFS_ERROR value on failure.
- */
-SQFS_API int sqfs_xattr_reader_get_desc(sqfs_xattr_reader_t *xr, sqfs_u32 idx,
-					sqfs_xattr_id_t *desc);
-
-/**
- * @brief Resolve an xattr index from an inode to an xattr description
- *
- * @memberof sqfs_xattr_reader_t
- *
- * This function takes an xattr descriptor object and seeks to the meta data
- * block containing the key-value pairs. The individual pairs can then be read
- * using consecutive calls to @ref sqfs_xattr_reader_read_key and
- * @ref sqfs_xattr_reader_read_value.
- *
- * @param xr A pointer to an xattr reader instance
- * @param desc The descriptor holding the location of the key-value pairs
- *
- * @return Zero on success, a negative @ref E_SQFS_ERROR value on failure.
- */
-SQFS_API int sqfs_xattr_reader_seek_kv(sqfs_xattr_reader_t *xr,
-				       const sqfs_xattr_id_t *desc);
-
-/**
- * @brief Read the next xattr key
- *
- * @memberof sqfs_xattr_reader_t
- *
- * After setting the start position using @ref sqfs_xattr_reader_seek_kv, this
- * function reads and decodes an xattr key and advances the internal position
- * indicator to the location after the key. The value can then be read using
- * using @ref sqfs_xattr_reader_read_value. After reading the value, the next
- * key can be read by calling this function again.
- *
- * @param xr A pointer to an xattr reader instance
- * @param key_out Used to return the decoded key. The underlying memory can be
- *                released using a single free() call.
- *
- * @return Zero on success, a negative @ref E_SQFS_ERROR value on failure.
- */
-SQFS_API
-int sqfs_xattr_reader_read_key(sqfs_xattr_reader_t *xr,
-			       sqfs_xattr_entry_t **key_out);
-
-/**
- * @brief Read the xattr value belonging to the last read key
- *
- * @memberof sqfs_xattr_reader_t
- *
- * After calling @ref sqfs_xattr_reader_read_key, this function can read and
- * decode the asociated value. The internal location indicator is then advanced
- * past the key to the next value, so @ref sqfs_xattr_reader_read_key can be
- * called again to read the next key.
- *
- * @param xr A pointer to an xattr reader instance.
- * @param key A pointer to the decoded key object.
- * @param val_out Used to return the decoded value. The underlying memory can
- *                be released using a single free() call.
- *
- * @return Zero on success, a negative @ref E_SQFS_ERROR value on failure.
- */
-SQFS_API
-int sqfs_xattr_reader_read_value(sqfs_xattr_reader_t *xr,
-				 const sqfs_xattr_entry_t *key,
-				 sqfs_xattr_value_t **val_out);
-
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/sqfs/xattr_reader.h b/include/sqfs/xattr_reader.h
new file mode 100644
index 0000000..6544a21
--- /dev/null
+++ b/include/sqfs/xattr_reader.h
@@ -0,0 +1,201 @@
+/* SPDX-License-Identifier: LGPL-3.0-or-later */
+/*
+ * xattr_reader.h - This file is part of libsquashfs
+ *
+ * Copyright (C) 2019 David Oberhollenzer <goliath@infraroot.at>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+#ifndef SQFS_XATTR_READER_H
+#define SQFS_XATTR_READER_H
+
+#include "sqfs/predef.h"
+
+/**
+ * @file xattr_reader.h
+ *
+ * @brief Contains declarations for the @ref sqfs_xattr_reader_t.
+ */
+
+/**
+ * @struct sqfs_xattr_reader_t
+ *
+ * @brief Abstracts read access to extended attributes in a SquashFS filesystem
+ *
+ * SquashFS stores extended attributes using multiple levels of indirection.
+ * First of all, the key-value pairs of each inode (that has extended
+ * attributes) are deduplicated and stored consecutively in meta data blocks.
+ * Furthermore, a value can be stored out-of-band, i.e. it holds a reference to
+ * another location from which the value has to be read.
+ *
+ * For each unique set of key-value pairs, a descriptor object is generated
+ * that holds the location of the first pair, the number of pairs and the total
+ * size used on disk. The array of descriptor objects is stored in multiple
+ * meta data blocks. Each inode that has extended attributes holds a 32 bit
+ * index into the descriptor array.
+ *
+ * The third layer of indirection is yet another table that points to the
+ * locations of the previous two tables. Its location is in turn stored in
+ * the super block.
+ *
+ * The sqfs_xattr_reader_t data structure takes care of the low level details
+ * of loading and parsing the data.
+ *
+ * After creating an instance using @ref sqfs_xattr_reader_create, simply call
+ * @ref sqfs_xattr_reader_load_locations to load and parse all of the location
+ * tables. Then use @ref sqfs_xattr_reader_get_desc to resolve a 32 bit index
+ * from an inode to a descriptor structure. Use @ref sqfs_xattr_reader_seek_kv
+ * to point the reader to the start of the key-value pairs and the call
+ * @ref sqfs_xattr_reader_read_key and @ref sqfs_xattr_reader_read_value
+ * consecutively to read and decode each key-value pair.
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Create an xattr reader
+ *
+ * @memberof sqfs_xattr_reader_t
+ *
+ * This function creates an object that abstracts away read only access to
+ * the extended attributes in a SquashFS filesystem.
+ *
+ * After creating a reader and before using it, call
+ * @ref sqfs_xattr_reader_load_locations to load and parse the location
+ * information required to look up xattr key-value pairs.
+ *
+ * All pointers passed to this function are stored internally for later use.
+ * Do not destroy any of the pointed to objects before destroying the xattr
+ * reader.
+ *
+ * @param file A pointer to a file object that contains the SquashFS filesystem
+ * @param super A pointer to the SquashFS super block required to find the
+ *              location tables.
+ * @param cmp A pointer to a compressor used to uncompress the loaded meta data
+ *            blocks.
+ *
+ * @return A pointer to a new xattr reader instance on success, NULL on
+ *         allocation failure.
+ */
+SQFS_API sqfs_xattr_reader_t *sqfs_xattr_reader_create(sqfs_file_t *file,
+						       sqfs_super_t *super,
+						       sqfs_compressor_t *cmp);
+
+/**
+ * @brief Destroy an xattr reader and free all memory used by it
+ *
+ * @memberof sqfs_xattr_reader_t
+ *
+ * @param xr A pointer to an xattr reader instance
+ */
+SQFS_API void sqfs_xattr_reader_destroy(sqfs_xattr_reader_t *xr);
+
+/**
+ * @brief Load the locations of the xattr meta data blocks into memory
+ *
+ * @memberof sqfs_xattr_reader_t
+ *
+ * This function must be called explicitly after an xattr reader has been
+ * created to load the actual location table from disk.
+ *
+ * @return Zero on success, a negative @ref E_SQFS_ERROR value on failure.
+ */
+SQFS_API int sqfs_xattr_reader_load_locations(sqfs_xattr_reader_t *xr);
+
+/**
+ * @brief Resolve an xattr index from an inode to an xattr description
+ *
+ * @memberof sqfs_xattr_reader_t
+ *
+ * This function takes an xattr index from an extended inode type and resolves
+ * it to a descriptor that points to location of the key-value pairs and
+ * indicates how many key-value pairs to read from there.
+ *
+ * @param xr A pointer to an xattr reader instance
+ * @param idx The xattr index to resolve
+ * @param desc Used to return the description
+ *
+ * @return Zero on success, a negative @ref E_SQFS_ERROR value on failure.
+ */
+SQFS_API int sqfs_xattr_reader_get_desc(sqfs_xattr_reader_t *xr, sqfs_u32 idx,
+					sqfs_xattr_id_t *desc);
+
+/**
+ * @brief Resolve an xattr index from an inode to an xattr description
+ *
+ * @memberof sqfs_xattr_reader_t
+ *
+ * This function takes an xattr descriptor object and seeks to the meta data
+ * block containing the key-value pairs. The individual pairs can then be read
+ * using consecutive calls to @ref sqfs_xattr_reader_read_key and
+ * @ref sqfs_xattr_reader_read_value.
+ *
+ * @param xr A pointer to an xattr reader instance
+ * @param desc The descriptor holding the location of the key-value pairs
+ *
+ * @return Zero on success, a negative @ref E_SQFS_ERROR value on failure.
+ */
+SQFS_API int sqfs_xattr_reader_seek_kv(sqfs_xattr_reader_t *xr,
+				       const sqfs_xattr_id_t *desc);
+
+/**
+ * @brief Read the next xattr key
+ *
+ * @memberof sqfs_xattr_reader_t
+ *
+ * After setting the start position using @ref sqfs_xattr_reader_seek_kv, this
+ * function reads and decodes an xattr key and advances the internal position
+ * indicator to the location after the key. The value can then be read using
+ * using @ref sqfs_xattr_reader_read_value. After reading the value, the next
+ * key can be read by calling this function again.
+ *
+ * @param xr A pointer to an xattr reader instance
+ * @param key_out Used to return the decoded key. The underlying memory can be
+ *                released using a single free() call.
+ *
+ * @return Zero on success, a negative @ref E_SQFS_ERROR value on failure.
+ */
+SQFS_API
+int sqfs_xattr_reader_read_key(sqfs_xattr_reader_t *xr,
+			       sqfs_xattr_entry_t **key_out);
+
+/**
+ * @brief Read the xattr value belonging to the last read key
+ *
+ * @memberof sqfs_xattr_reader_t
+ *
+ * After calling @ref sqfs_xattr_reader_read_key, this function can read and
+ * decode the asociated value. The internal location indicator is then advanced
+ * past the key to the next value, so @ref sqfs_xattr_reader_read_key can be
+ * called again to read the next key.
+ *
+ * @param xr A pointer to an xattr reader instance.
+ * @param key A pointer to the decoded key object.
+ * @param val_out Used to return the decoded value. The underlying memory can
+ *                be released using a single free() call.
+ *
+ * @return Zero on success, a negative @ref E_SQFS_ERROR value on failure.
+ */
+SQFS_API
+int sqfs_xattr_reader_read_value(sqfs_xattr_reader_t *xr,
+				 const sqfs_xattr_entry_t *key,
+				 sqfs_xattr_value_t **val_out);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* SQFS_XATTR_READER_H */