1 files changed, 107 insertions, 0 deletions
diff --git a/include/sqfs/io.h b/include/sqfs/io.h
index 389f875..e851ea1 100644
--- a/include/sqfs/io.h
+++ b/include/sqfs/io.h
@@ -292,6 +292,90 @@ struct sqfs_ostream_t {
 	const char *(*get_filename)(sqfs_ostream_t *strm);
 };
 
+/**
+ * @interface sqfs_dir_iterator_t
+ *
+ * @extends sqfs_object_t
+ *
+ * @brief An iterator over entries in a filesystem directory.
+ */
+struct sqfs_dir_iterator_t {
+	sqfs_object_t obj;
+
+	/**
+	 * @brief Read the next entry and update internal state relating to it
+	 *
+	 * @param it A pointer to the iterator itself
+	 * @param out Returns a pointer to an entry on success. Has to be
+	 *            released with @ref sqfs_free().
+	 *
+	 * @return Zero on success, postivie value if the end of the list was
+	 *         reached, negative @ref SQFS_ERROR value on failure.
+	 */
+	int (*next)(sqfs_dir_iterator_t *it, sqfs_dir_entry_t **out);
+
+	/**
+	 * @brief If the last entry was a symlink, extract the target path
+	 *
+	 * @param it A pointer to the iterator itself.
+	 * @param out Returns a pointer to a string on success. Has to be
+	 *            released with @ref sqfs_free().
+	 *
+	 * @return Zero on success, negative @ref SQFS_ERROR value on failure.
+	 */
+	int (*read_link)(sqfs_dir_iterator_t *it, char **out);
+
+	/**
+	 * @brief If the last entry was a directory, open it.
+	 *
+	 * If next() returned a directory, this can be used to create a brand
+	 * new sqfs_dir_iterator_t for it, that is independent of the current
+	 * one and returns the sub-directories entries.
+	 *
+	 * @param it A pointer to the iterator itself.
+	 * @param out Returns a pointer to a directory iterator on success.
+	 *
+	 * @return Zero on success, negative @ref SQFS_ERROR value on failure.
+	 */
+	int (*open_subdir)(sqfs_dir_iterator_t *it,
+			   sqfs_dir_iterator_t **out);
+
+	/**
+	 * @brief Skip a sub-hierarchy on a stacked iterator
+	 *
+	 * If an iterator would ordinarily recurse into a sub-directory,
+	 * tell it to skip those entries. On simple, flag iterators like the
+	 * one returned by @ref dir_iterator_create, this has no effect.
+	 *
+	 * @param it A pointer to the iterator itself.
+	 */
+	void (*ignore_subdir)(sqfs_dir_iterator_t *it);
+
+	/**
+	 * @brief If the last entry was a regular file, open it.
+	 *
+	 * If next() returned a file, this can be used to create an istream
+	 * to read from it.
+	 *
+	 * @param it A pointer to the iterator itself.
+	 * @param out Returns a pointer to a @ref sqfs_istream_t on success.
+	 *
+	 * @return Zero on success, negative @ref SQFS_ERROR value on failure.
+	 */
+	int (*open_file_ro)(sqfs_dir_iterator_t *it, sqfs_istream_t **out);
+
+	/**
+	 * @brief Read extended attributes associated with the current entry
+	 *
+	 * @param it A pointer to the iterator itself.
+	 * @param out Returns a linked list of xattr entries. Has to be
+	 *            released with @ref sqfs_xattr_list_free().
+	 *
+	 * @return Zero on success, negative @ref SQFS_ERROR value on failure.
+	 */
+	int (*read_xattr)(sqfs_dir_iterator_t *it, sqfs_xattr_t **out);
+};
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -499,6 +583,29 @@ SQFS_API int sqfs_istream_skip(sqfs_istream_t *strm, sqfs_u64 size);
 SQFS_API sqfs_s32 sqfs_istream_splice(sqfs_istream_t *in, sqfs_ostream_t *out,
 				      sqfs_u32 size);
 
+/**
+ * @brief Construct a simple directory iterator given a path
+ *
+ * @memberof sqfs_dir_iterator_t
+ *
+ * On systems with encoding aware file I/O (like Windows), the path is
+ * interpreted to be UTF-8 encoded and converted to the native system API
+ * encoding to open the directory. For each directory entry, the name in
+ * the native encoding is converted back to UTF-8 when reading.
+ *
+ * The implementation returned by this is simple, non-recursive, reporting
+ * directory contents as returned by the OS native API, i.e. not sorted,
+ * and including the "." and ".." entries.
+ *
+ * @param path A path to a directory on the file system.
+ *
+ * @return A pointer to a sqfs_dir_iterator_t implementation on success,
+ *         NULL on error (message is printed to stderr).
+ */
+SQFS_API int sqfs_dir_iterator_create_native(sqfs_dir_iterator_t **out,
+					     const char *path,
+					     sqfs_u32 flags);
+
 #ifdef __cplusplus
 }
 #endif