/**
 * @file llfs.h
 * @brief Linked List Filesystem header (llfs)
 * @author Lorenz C.
 * @version 0.1.1
 */

#ifndef LLFS_H
#define LLFS_H

#include <stddef.h>
#include <stdint.h>

/**
 * @brief Representation of a file in the llfs filesystem
 */
typedef struct llfs_file {
    const uint8_t* data; // Pointer to the file data (len bytes)
    const char* name;    // Null-terminated string with the filename
    size_t len;          // Length of the file data
} llfs_file_t;

/**
 * @brief Internal representation of a file in the filesystem
 * @warning This struct should only be used in the llfs_data.c file.
 */
struct llfs_data_file {
    const uint8_t* data;
    const char* name;
    const size_t len;
    const struct llfs_data_file* next;
};

/**
 * @brief Initialize the llfs filesystem
 * @note This function should be called before any other llfs function or POSIX file operation (e.g. fopen, fread, ...)
 * @return 0 on success
 */
int8_t llfs_init(void);

/**
 * @brief Get a list of files in the filesystem
 * Get a list of all the files in the filesystem.
 *
 * Use the filter to filter out files with a filename that do not match the file extension filter.
 *
 * The following members of the llfs_file_t struct are set: name, len and data. @ref llfs_file_t
 *
 *
 * @param[out] file_list A pointer to an array of llfs_file_t to store the files in @ref llfs_file_t
 * @param[in] max_files The maximum number of files to return (size of file_list)
 * @param[in] filter A string with the file extensions to filter out. (e.g. "*.txt" or "*.png")
 * @return The number of files returned
 */
size_t llfs_file_list(llfs_file_t* file_list, size_t max_files, char* filter);

/**
 * @brief Open a file
 * Get a file from the filesystem by name.
 *
 * @param[in] name The name of the file to open
 * @return A pointer to a llfs_file_t with the file data @ref llfs_file_t
 *         NULL if the file does not exist
 */
llfs_file_t* llfs_file_open(const char* name);

/**
 * @brief Iterate over all files in the filesystem
 * For each call (with the same mem pointer) the next file in the filesystem is returned.
 * The first call should be with mem = NULL.
 * If a filter is specified, only files with a filename that matches the filter are returned.
 *
 * @param[in, out] mem A pointer to a void* that is used internally to keep track of the current file
 * @param[in] filter  A string with file extension to filter out. (e.g. "*.txt" or "*.png")
 * @return The next file in the filesystem or NULL if there are no more files @ref llfs_file_t
 */
llfs_file_t* llfs_next_file(void** mem, char* filter);

/**
 * @brief Get the number of files in the filesystem
 *
 * @return The number of files in the filesystem
 */
size_t llfs_file_count(void);

#endif // LLFS_H
