IFileSystem.h

Go to the documentation of this file.

/****
 * IFileSystem.h
 * Abstract filesystem interface definitions
 *
 * Created: August 2018
 *
 * Copyright 2019 mikee47 <mike@sillyhouse.net>
 *
 * This file is part of the IFS Library
 *
 * This library is free software: you can redistribute it and/or modify it under the terms of the
 * GNU General Public License as published by the Free Software Foundation, version 3 or later.
 *
 * This library 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 General Public License along with this library.
 * If not, see <https://www.gnu.org/licenses/>.
 *
 ****/
 
#pragma once
 
#include "Stat.h"
#include "OpenFlags.h"
#include <Storage/Partition.h>
#include "Error.h"
#include "Control.h"
#include "Profiler.h"
#include "Attribute.h"
#include "Extent.h"
#include <Data/Stream/SeekOrigin.h>
 
#define FILESYSTEM_TYPE_MAP(XX)                                                                                        \
    XX(Unknown, NULL, "Unknown")                                                                                       \
    XX(FWFS, FWFS, "Firmware File System")                                                                             \
    XX(SPIFFS, SPIF, "SPI Flash File System (SPIFFS)")                                                                 \
    XX(LittleFS, LFS, "Little FS")                                                                                     \
    XX(Hybrid, HYFS, "Hybrid File System")                                                                             \
    XX(Host, HOST, "Host File System")                                                                                 \
    XX(Fat, FAT, "FAT File System")                                                                                    \
    XX(Fat32, FAT32, "FAT32 File System")                                                                              \
    XX(ExFat, exFAT, "EXFAT File System")
 
#define FILE_SYSTEM_ATTR_MAP(XX)                                                                                       \
    XX(Mounted, "Filing system is mounted and in use")                                                                 \
    XX(ReadOnly, "Writing not permitted to this volume")                                                               \
    XX(Virtual, "Virtual filesystem, doesn't host files directly")                                                     \
    XX(Check, "Volume check recommended")                                                                              \
    XX(NoMeta, "Metadata unsupported")
 
namespace IFS
{
class IFileSystem;
 
/*
 * Opaque structure for directory reading
 */
using DirHandle = struct ImplFileDir*;
 
#if DEBUG_BUILD
#define debug_ifserr(err, func, ...)                                                                                   \
    do {                                                                                                               \
        [[maybe_unused]] int errorCode = err;                                                                          \
        debug_e(func ": %s (%d)", ##__VA_ARGS__, getErrorString(errorCode).c_str(), err);                              \
    } while(0)
#else
#define debug_ifserr(err, func, ...)                                                                                   \
    do {                                                                                                               \
    } while(0)
#endif
 
class IFileSystem
{
public:
    enum class Type {
#define XX(_name, _tag, _desc) _name,
        FILESYSTEM_TYPE_MAP(XX)
#undef XX
            MAX
    };
 
    enum class Attribute {
#define XX(_tag, _comment) _tag,
        FILE_SYSTEM_ATTR_MAP(XX)
#undef XX
            MAX
    };
 
    // The set of attributes
    using Attributes = BitSet<uint8_t, Attribute, size_t(Attribute::MAX)>;
 
    struct Info {
        Type type{};               
        Attributes attr{};         
        size_t maxNameLength{255}; 
        size_t maxPathLength{255}; 
        Storage::Partition partition;
        uint32_t volumeID{0};        
        NameBuffer name;             
        volume_size_t volumeSize{0}; 
        volume_size_t freeSpace{0};  
        TimeStamp creationTime{};
 
        Info() = default;
 
        Info(char* namebuf, unsigned buflen) : name(namebuf, buflen)
        {
        }
 
        volume_size_t used() const
        {
            return volumeSize - freeSpace;
        }
 
        Info& operator=(const Info& rhs)
        {
            type = rhs.type;
            partition = rhs.partition;
            attr = rhs.attr;
            volumeID = rhs.volumeID;
            name.copy(rhs.name);
            volumeSize = rhs.volumeSize;
            freeSpace = rhs.freeSpace;
            return *this;
        }
 
        void clear()
        {
            *this = Info{};
        }
 
        size_t printTo(Print& p) const;
    };
 
    struct NameInfo : public Info {
    public:
        NameInfo() : Info(buffer, sizeof(buffer))
        {
        }
 
    private:
        char buffer[256];
    };
 
    virtual ~IFileSystem() = default;
 
    virtual int mount() = 0;
 
    virtual int getinfo(Info& info) = 0;
 
    virtual int setProfiler(IProfiler*)
    {
        return Error::NotImplemented;
    }
 
    virtual String getErrorString(int err)
    {
        return Error::toString(err);
    }
 
    virtual int setVolume([[maybe_unused]] uint8_t index, [[maybe_unused]] IFileSystem* fileSystem)
    {
        return Error::NotSupported;
    }
 
    virtual int opendir(const char* path, DirHandle& dir) = 0;
 
    virtual int readdir(DirHandle dir, Stat& stat) = 0;
 
    virtual int rewinddir(DirHandle dir) = 0;
 
    virtual int closedir(DirHandle dir) = 0;
 
    virtual int mkdir(const char* path) = 0;
 
    virtual int stat(const char* path, Stat* stat) = 0;
 
    virtual int fstat(FileHandle file, Stat* stat) = 0;
 
    virtual int fcontrol([[maybe_unused]] FileHandle file, [[maybe_unused]] ControlCode code,
                         [[maybe_unused]] void* buffer, [[maybe_unused]] size_t bufSize)
    {
        return Error::NotSupported;
    }
 
    virtual FileHandle open(const char* path, OpenFlags flags) = 0;
 
    virtual int close(FileHandle file) = 0;
 
    virtual int read(FileHandle file, void* data, size_t size) = 0;
 
    virtual int write(FileHandle file, const void* data, size_t size) = 0;
 
    virtual file_offset_t lseek(FileHandle file, file_offset_t offset, SeekOrigin origin) = 0;
 
    virtual int eof(FileHandle file) = 0;
 
    virtual file_offset_t tell(FileHandle file) = 0;
 
    virtual int ftruncate(FileHandle file, file_size_t new_size) = 0;
 
    virtual int flush(FileHandle file) = 0;
 
    virtual int fsetxattr(FileHandle file, AttributeTag tag, const void* data, size_t size) = 0;
 
    virtual int fgetxattr(FileHandle file, AttributeTag tag, void* buffer, size_t size) = 0;
 
    virtual int fenumxattr(FileHandle file, AttributeEnumCallback callback, void* buffer, size_t bufsize) = 0;
 
    virtual int setxattr(const char* path, AttributeTag tag, const void* data, size_t size) = 0;
 
    virtual int getxattr(const char* path, AttributeTag tag, void* buffer, size_t size) = 0;
 
    virtual int fgetextents([[maybe_unused]] FileHandle file, [[maybe_unused]] Storage::Partition* part,
                            [[maybe_unused]] Extent* list, [[maybe_unused]] uint16_t extcount)
    {
        return Error::NotImplemented;
    }
 
    virtual int rename(const char* oldpath, const char* newpath) = 0;
 
    virtual int remove(const char* path) = 0;
 
    virtual int fremove(FileHandle file) = 0;
 
    virtual int format() = 0;
 
    virtual int check()
    {
        return Error::NotImplemented;
    }
};
 
} // namespace IFS
 
String toString(IFS::IFileSystem::Type type);
 
String toString(IFS::IFileSystem::Attribute attr);