Add an API for directory iteration

include/rcutils/filesystem.h

@@ -26,6 +26,7 @@ extern "C"
 
 #include "rcutils/allocator.h"
 #include "rcutils/macros.h"
+#include "rcutils/types.h"
 #include "rcutils/visibility_control.h"
 
 /// Return current working directory.
@@ -243,6 +244,75 @@ RCUTILS_PUBLIC
 size_t
 rcutils_get_file_size(const char * file_path);
 
+/// An iterator used for enumerating directory contents
+typedef struct rcutils_dir_iter_t
+{
+  /// The name of the enumerated file or directory
+  const char * entry_name;
+  /// The allocator used internally by iteration functions
+  rcutils_allocator_t allocator;
+  /// The platform-specific iteration state
+  void * state;
+} rcutils_dir_iter_t;
+
+/// Begin iterating over the contents of the specified directory.
+/*
+ * This function is used to list the file and directories that are contained in
+ * a specified directory. The structure returned by it must be deallocated using
+ * ::rcutils_dir_iter_end when the iteration is completed. The name of the
+ * enumerated entry is stored in the `entry_name` member of the returned object,
+ * and the first entry is already populated upon completion of this function. To
+ * populate the entry with the name of the next entry, use the
+ * ::rcutils_dir_iter_next function. Note that the "." and ".." entries are
+ * typically among the entries enumerated.
+ * \param[in] directory_path The directory path to iterate over the contents of.
+ * \param[in] allocator Allocator used to create the returned structure.
+ * \return An iterator object used to continue iterating directory contents
+ * \return NULL if an error occurred
+ */
+RCUTILS_PUBLIC
+rcutils_dir_iter_t *
+rcutils_dir_iter_start(const char * directory_path, const rcutils_allocator_t allocator);
+
+/// Continue iterating over the contents of a directory.
+/*
+ * \param[in] iter An iterator created by ::rcutils_dir_iter_start.
+ * \return `True` if another entry was found
+ * \return `False` if there are no more entries in the directory
+ */
+RCUTILS_PUBLIC
+bool
+rcutils_dir_iter_next(rcutils_dir_iter_t * iter);
+
+/// Finish iterating over the contents of a directory.
+/*
+ * \param[in] iter An iterator created by ::rcutils_dir_iter_start.
+ */
+RCUTILS_PUBLIC
+void
+rcutils_dir_iter_end(rcutils_dir_iter_t * iter);
+
+/// List the entries present in a directory.
+/**
+ * This function lists the name of each file or directory present in the given
+ * directory in an implementation-specific order.
+ *
+ * \param[in] directory_path The directory path to list the contents of.
+ * \param[in] allocator Allocator being used for resources in the string_array.
+ * \param[out] string_array The object to store the entries into.
+ * \return `RCUTILS_RET_OK` if successful, or
+ * \return `RCUTILS_RET_INVALID_ARGUMENT` for invalid arguments, or
+ * \return `RCUTILS_RET_BAD_ALLOC` if memory allocation fails, or
+ * \return `RCUTILS_RET_ERROR` if an unknown error occurs
+ */
+RCUTILS_PUBLIC
+RCUTILS_WARN_UNUSED
+rcutils_ret_t
+rcutils_list_directory(
+  const char * directory_path,
+  rcutils_allocator_t allocator,
+  rcutils_string_array_t * string_array);
+
 #ifdef __cplusplus
 }
 #endif