matos/core/fsEntry.h

#pragma once

#include "fs.h"
#include "stdint.h"
#include "stddef.h"

/**
 * Those structures aimes to represent VFS directory entries in memory.
 * It's the equivalent of the Linux dentry or SimpleOs sos_fs_nscache_node.
 */

/**
 * Path or Pascal String
 * */
struct pstr {
    size_t len;
    const char *name;
};

#define PSTR_INIT(n, l)                                                                       \
    {                                                                                         \
        .len = l, .name = n                                                                   \
    }


/**
 * @brief Structure representing a file system entry.
 *
 * This structure holds information about a file system entry,
 * including its name, associated inode, relationships within
 * the file system hierarchy, and reference count.
 */
struct fsEntry {
    struct pstr name;
    struct inode *node;

    struct fsEntry *parent;     // parent directory
    struct fsEntry *mountpoint; // if this is a mounted fs, point to mountpoint
    struct fsEntry *mountedFs;  // Fs possibly mounted on this fsEntry

    struct fsEntry *childs;                      // point to the list of children
    struct fsEntry *nextSiblings, *prevSiblings; // Sibling at the same level

    uint ref; // reference counter
};

/**
 * @brief Splits a pstr path into upper and lower components.
 *
 * This function takes a path and splits it into an upper component
 * (the first segment of the path) and a lower component (the rest of the path).
 *
 * @param path Pointer to the input pstr structure representing the path.
 * @param upper Pointer to the pstr structure to store the upper component.
 * @param lower Pointer to the pstr structure to store the lower component.
 * @return bool_t Returns true if there is a lower component, false otherwise.
 */
bool_t pstringSplipPath(struct pstr *path, struct pstr *upper, struct pstr *lower);

/**
 * @brief Compares two pstr structures to check if they are equal.
 *
 * This function compares the length and the content of the strings
 * in the two provided pstr structures.
 *
 * @param a Pointer to the first pstr structure.
 * @param b Pointer to the second pstr structure.
 * @return int Returns 1 if the structures are equal, 0 otherwise.
 */
bool_t pstringIsEq(struct pstr *p1, struct pstr *p2);

/**
 * @brief Increments the reference count of a file system entry.
 *
 * This function increments the reference count of the given file system
 * entry. It is typically used to manage the lifecycle of file system
 * entries, ensuring that they are not prematurely deallocated.
 *
 * @param entry Pointer to the fsEntry structure whose reference count will be incremented.
 * @return int Returns 0 on success.
 */
int fsEntryRef(struct fsEntry *entry);

/**
 * @brief Decrements the reference count of a file system entry.
 *
 * This function decrements the reference count of the given file system
 * entry. It is typically used to manage the lifecycle of file system
 * entries, ensuring that they are not prematurely deallocated.
 *
 * @param entry Pointer to the fsEntry structure whose reference count will be incremented.
 * @return int Returns 0 on success.
 */
int fsEntryUnref(struct fsEntry **entry);

/**
 * @brief Creates a new child fsEntry under the specified parent.
 *
 * This function allocates and initializes a new fsEntry structure
 * representing a file system entry. The new entry is added as a child
 * of the specified parent. It also handles reference counting for
 * the parent entry and the associated inode.
 *
 * @param parent Pointer to the parent fsEntry. Can be NULL if the new entry has no parent.
 * @param name Pointer to the pstr structure representing the name of the new entry. Can be NULL.
 * @param inode Pointer to the inode associated with the new entry.
 * @param result Pointer to a location where the pointer to the newly created fsEntry will be stored.
 * @return int Returns 0 on success, or a negative error code on failure.
 *         -ENOMEM if memory allocation fails.
 */
int fsEntryNewChild(struct fsEntry *parent, const struct pstr *name, struct inode *inode,
                    struct fsEntry **result);

/**
 * @brief Setup the fsEntry subsystem
 *
 */
int fsEntrySetup(void);