IFileSystem.h
Go to the documentation of this file.
1 /****
2  * IFileSystem.h
3  * Abstract filesystem interface definitions
4  *
5  * Created: August 2018
6  *
7  * Copyright 2019 mikee47 <mike@sillyhouse.net>
8  *
9  * This file is part of the IFS Library
10  *
11  * This library is free software: you can redistribute it and/or modify it under the terms of the
12  * GNU General Public License as published by the Free Software Foundation, version 3 or later.
13  *
14  * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
15  * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
16  * See the GNU General Public License for more details.
17  *
18  * You should have received a copy of the GNU General Public License along with this library.
19  * If not, see <https://www.gnu.org/licenses/>.
20  *
21  ****/
22 
28 #pragma once
29 
30 #include "Stat.h"
31 #include "OpenFlags.h"
32 #include <Storage/Partition.h>
33 #include "Error.h"
34 #include "Control.h"
35 #include "Profiler.h"
36 #include "Attribute.h"
37 #include "Extent.h"
38 #include <Data/Stream/SeekOrigin.h>
39 
44 #define FILESYSTEM_TYPE_MAP(XX) \
45  XX(Unknown, NULL, "Unknown") \
46  XX(FWFS, FWFS, "Firmware File System") \
47  XX(SPIFFS, SPIF, "SPI Flash File System (SPIFFS)") \
48  XX(LittleFS, LFS, "Little FS") \
49  XX(Hybrid, HYFS, "Hybrid File System") \
50  XX(Host, HOST, "Host File System") \
51  XX(Fat, FAT, "FAT File System") \
52  XX(Fat32, FAT32, "FAT32 File System") \
53  XX(ExFat, exFAT, "EXFAT File System")
54 
58 #define FILE_SYSTEM_ATTR_MAP(XX) \
59  XX(Mounted, "Filing system is mounted and in use") \
60  XX(ReadOnly, "Writing not permitted to this volume") \
61  XX(Virtual, "Virtual filesystem, doesn't host files directly") \
62  XX(Check, "Volume check recommended") \
63  XX(NoMeta, "Metadata unsupported")
64 
65 namespace IFS
66 {
67 class IFileSystem;
68 
69 /*
70  * Opaque structure for directory reading
71  */
72 using DirHandle = struct ImplFileDir*;
73 
74 #if DEBUG_BUILD
75 #define debug_ifserr(err, func, ...) \
76  do { \
77  int errorCode = err; \
78  (void)errorCode; \
79  debug_e(func ": %s (%d)", ##__VA_ARGS__, getErrorString(errorCode).c_str(), err); \
80  } while(0)
81 #else
82 #define debug_ifserr(err, func, ...) \
83  do { \
84  } while(0)
85 #endif
86 
100 {
101 public:
102  enum class Type {
103 #define XX(_name, _tag, _desc) _name,
105 #undef XX
106  MAX
107  };
108 
109  enum class Attribute {
110 #define XX(_tag, _comment) _tag,
112 #undef XX
113  MAX
114  };
115 
116  // The set of attributes
117  using Attributes = BitSet<uint8_t, Attribute, size_t(Attribute::MAX)>;
118 
122  struct Info {
123  Type type{};
125  size_t maxNameLength{255};
126  size_t maxPathLength{255};
128  uint32_t volumeID{0};
133 
135  {
136  }
137 
138  Info(char* namebuf, unsigned buflen) : name(namebuf, buflen)
139  {
140  }
141 
143  {
144  return volumeSize - freeSpace;
145  }
146 
147  Info& operator=(const Info& rhs)
148  {
149  type = rhs.type;
150  partition = rhs.partition;
151  attr = rhs.attr;
152  volumeID = rhs.volumeID;
153  name.copy(rhs.name);
154  volumeSize = rhs.volumeSize;
155  freeSpace = rhs.freeSpace;
156  return *this;
157  }
158 
159  void clear()
160  {
161  *this = Info{};
162  }
163 
164  size_t printTo(Print& p) const;
165  };
166 
170  struct NameInfo : public Info {
171  public:
172  NameInfo() : Info(buffer, sizeof(buffer))
173  {
174  }
175 
176  private:
177  char buffer[256];
178  };
179 
183  virtual ~IFileSystem()
184  {
185  }
186 
191  virtual int mount() = 0;
192 
198  virtual int getinfo(Info& info) = 0;
199 
205  virtual int setProfiler(IProfiler* profiler)
206  {
207  return Error::NotImplemented;
208  }
209 
214  virtual String getErrorString(int err)
215  {
216  return Error::toString(err);
217  }
218 
225  virtual int setVolume(uint8_t index, IFileSystem* fileSystem)
226  {
227  return Error::NotSupported;
228  }
229 
236  virtual int opendir(const char* path, DirHandle& dir) = 0;
237 
246  virtual int readdir(DirHandle dir, Stat& stat) = 0;
247 
253  virtual int rewinddir(DirHandle dir) = 0;
254 
260  virtual int closedir(DirHandle dir) = 0;
261 
271  virtual int mkdir(const char* path) = 0;
272 
290  virtual int stat(const char* path, Stat* stat) = 0;
291 
298  virtual int fstat(FileHandle file, Stat* stat) = 0;
299 
312  virtual int fcontrol(FileHandle file, ControlCode code, void* buffer, size_t bufSize)
313  {
314  return Error::NotSupported;
315  }
316 
327  virtual FileHandle open(const char* path, OpenFlags flags) = 0;
328 
334  virtual int close(FileHandle file) = 0;
335 
343  virtual int read(FileHandle file, void* data, size_t size) = 0;
344 
352  virtual int write(FileHandle file, const void* data, size_t size) = 0;
353 
361  virtual file_offset_t lseek(FileHandle file, file_offset_t offset, SeekOrigin origin) = 0;
362 
368  virtual int eof(FileHandle file) = 0;
369 
375  virtual file_offset_t tell(FileHandle file) = 0;
376 
385  virtual int ftruncate(FileHandle file, file_size_t new_size) = 0;
386 
392  virtual int flush(FileHandle file) = 0;
393 
403  virtual int fsetxattr(FileHandle file, AttributeTag tag, const void* data, size_t size) = 0;
404 
413  virtual int fgetxattr(FileHandle file, AttributeTag tag, void* buffer, size_t size) = 0;
414 
423  virtual int fenumxattr(FileHandle file, AttributeEnumCallback callback, void* buffer, size_t bufsize) = 0;
424 
433  virtual int setxattr(const char* path, AttributeTag tag, const void* data, size_t size) = 0;
434 
443  virtual int getxattr(const char* path, AttributeTag tag, void* buffer, size_t size) = 0;
444 
453  virtual int fgetextents(FileHandle file, Storage::Partition* part, Extent* list, uint16_t extcount)
454  {
455  return Error::NotImplemented;
456  }
457 
464  virtual int rename(const char* oldpath, const char* newpath) = 0;
465 
471  virtual int remove(const char* path) = 0;
472 
478  virtual int fremove(FileHandle file) = 0;
479 
487  virtual int format() = 0;
488 
496  virtual int check()
497  {
498  return Error::NotImplemented;
499  }
500 };
501 
502 } // namespace IFS
503 
508 
513 
int32_t file_offset_t
Definition: Components/IFS/src/include/IFS/Types.h:51
storage_size_t volume_size_t
Definition: Components/IFS/src/include/IFS/Types.h:37
uint32_t file_size_t
Definition: Components/IFS/src/include/IFS/Types.h:50
SeekOrigin
Stream/file seek origins.
Definition: SeekOrigin.h:18
Definition: Delegate.h:20
Installable File System base class.
Definition: IFileSystem.h:100
virtual file_offset_t tell(FileHandle file)=0
get current file position
virtual int fsetxattr(FileHandle file, AttributeTag tag, const void *data, size_t size)=0
Set an extended attribute on an open file.
virtual int rename(const char *oldpath, const char *newpath)=0
rename a file
virtual int rewinddir(DirHandle dir)=0
Reset directory read position to start.
virtual String getErrorString(int err)
get the text for a returned error code
Definition: IFileSystem.h:214
Type
Definition: IFileSystem.h:102
XX(_name, _tag, _desc)
virtual int close(FileHandle file)=0
close an open file
virtual int opendir(const char *path, DirHandle &dir)=0
open a directory for reading
virtual int remove(const char *path)=0
remove (delete) a file by path
virtual int flush(FileHandle file)=0
flush any buffered data to physical media
virtual int setVolume(uint8_t index, IFileSystem *fileSystem)
Set volume for mountpoint.
Definition: IFileSystem.h:225
virtual int closedir(DirHandle dir)=0
close a directory object
virtual int stat(const char *path, Stat *stat)=0
get file information
virtual int fstat(FileHandle file, Stat *stat)=0
get file information
virtual int getxattr(const char *path, AttributeTag tag, void *buffer, size_t size)=0
Get an attribute from a file given its path.
virtual int check()
Perform a file system consistency check.
Definition: IFileSystem.h:496
virtual int write(FileHandle file, const void *data, size_t size)=0
write content to a file at current position and advance cursor
virtual int fgetxattr(FileHandle file, AttributeTag tag, void *buffer, size_t size)=0
Get an extended attribute from an open file.
virtual int fcontrol(FileHandle file, ControlCode code, void *buffer, size_t bufSize)
Low-level and non-standard file control operations.
Definition: IFileSystem.h:312
virtual int getinfo(Info &info)=0
get filing system information
Attribute
Definition: IFileSystem.h:109
virtual int fremove(FileHandle file)=0
remove (delete) a file by handle
virtual ~IFileSystem()
Filing system implementations should dismount and cleanup here.
Definition: IFileSystem.h:183
virtual int mount()=0
Mount file system, performing any required initialisation.
virtual int ftruncate(FileHandle file, file_size_t new_size)=0
Truncate (reduce) the size of an open file.
virtual int read(FileHandle file, void *data, size_t size)=0
read content from a file and advance cursor
virtual file_offset_t lseek(FileHandle file, file_offset_t offset, SeekOrigin origin)=0
change file read/write position
virtual int readdir(DirHandle dir, Stat &stat)=0
read a directory entry
virtual int format()=0
format the filing system
virtual int setxattr(const char *path, AttributeTag tag, const void *data, size_t size)=0
Set an extended attribute for a file given its path.
virtual int fgetextents(FileHandle file, Storage::Partition *part, Extent *list, uint16_t extcount)
Get extents for a file.
Definition: IFileSystem.h:453
virtual int setProfiler(IProfiler *profiler)
Set profiler instance to enable debugging and performance assessment.
Definition: IFileSystem.h:205
virtual int eof(FileHandle file)=0
determine if current file position is at end of file
virtual FileHandle open(const char *path, OpenFlags flags)=0
open a file (or directory) by path
virtual int mkdir(const char *path)=0
Create a directory.
virtual int fenumxattr(FileHandle file, AttributeEnumCallback callback, void *buffer, size_t bufsize)=0
Enumerate attributes.
Filesystems may optionally provide performance statistics.
Definition: Profiler.h:31
Provides formatted output to stream.
Definition: Print.h:37
Represents a flash partition.
Definition: Partition.h:86
The String class.
Definition: WString.h:137
String toString(IFS::IFileSystem::Type type)
Get String for filesystem type.
String toString(int err)
get text for an error code
#define FILE_SYSTEM_ATTR_MAP(XX)
Attribute flags for filing system.
Definition: IFileSystem.h:58
#define FILESYSTEM_TYPE_MAP(XX)
Four-character tag to identify type of filing system.
Definition: IFileSystem.h:44
Definition: DirectoryTemplate.h:37
ControlCode
See IFS::IFileSystem::fcontrol
Definition: Components/IFS/src/include/IFS/Control.h:31
struct ImplFileDir * DirHandle
Definition: IFileSystem.h:72
AttributeTag
Identifies a specific attribute.
Definition: Attribute.h:45
int16_t FileHandle
File handle.
Definition: Stat.h:40
Defines the location of a contiguous run of file data.
Definition: Extent.h:40
Basic information about filing system.
Definition: IFileSystem.h:122
TimeStamp creationTime
Definition: IFileSystem.h:132
size_t maxPathLength
Maximum length of a full file path.
Definition: IFileSystem.h:126
void clear()
Definition: IFileSystem.h:159
Storage::Partition partition
Definition: IFileSystem.h:127
Info()
Definition: IFileSystem.h:134
Info & operator=(const Info &rhs)
Definition: IFileSystem.h:147
size_t maxNameLength
Maximum length of a single file name.
Definition: IFileSystem.h:125
volume_size_t volumeSize
Size of volume, in bytes.
Definition: IFileSystem.h:130
Type type
The filing system type identifier.
Definition: IFileSystem.h:123
Attributes attr
Attribute flags.
Definition: IFileSystem.h:124
uint32_t volumeID
Unique identifier for volume.
Definition: IFileSystem.h:128
NameBuffer name
Buffer for name.
Definition: IFileSystem.h:129
size_t printTo(Print &p) const
Info(char *namebuf, unsigned buflen)
Definition: IFileSystem.h:138
volume_size_t used() const
Definition: IFileSystem.h:142
volume_size_t freeSpace
Available space, in bytes.
Definition: IFileSystem.h:131
Filing system information with buffer for name.
Definition: IFileSystem.h:170
NameInfo()
Definition: IFileSystem.h:172
defines a 'safe' name buffer
Definition: NameBuffer.h:44
int copy(const char *src, uint16_t srclen)
copies text from a source buffer into a name buffer
Definition: NameBuffer.h:95
File Status structure.
Definition: Stat.h:52
Manage IFS timestamps stored as an unsigned 32-bit value.
Definition: TimeStamp.h:37