IFileSystem.h
Go to the documentation of this file.
1 
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 <Data/Stream/SeekOrigin.h>
38 
43 #define FILESYSTEM_TYPE_MAP(XX) \
44  XX(Unknown, NULL, "Unknown") \
45  XX(FWFS, FWFS, "Firmware File System") \
46  XX(SPIFFS, SPIF, "SPI Flash File System (SPIFFS)") \
47  XX(LittleFS, LFS, "Little FS") \
48  XX(Hybrid, HYFS, "Hybrid File System") \
49  XX(Host, HOST, "Host File System")
50 
54 #define FILE_SYSTEM_ATTR_MAP(XX) \
55  XX(Mounted, "Filing system is mounted and in use") \
56  XX(ReadOnly, "Writing not permitted to this volume") \
57  XX(Virtual, "Virtual filesystem, doesn't host files directly") \
58  XX(Check, "Volume check recommended") \
59  XX(NoMeta, "Metadata unsupported")
60 
61 namespace IFS
62 {
63 class IFileSystem;
64 
65 /*
66  * Opaque structure for directory reading
67  */
68 using DirHandle = struct ImplFileDir*;
69 
70 #if DEBUG_BUILD
71 #define debug_ifserr(err, func, ...) \
72  do { \
73  int errorCode = err; \
74  (void)errorCode; \
75  debug_e(func ": %s (%d)", ##__VA_ARGS__, getErrorString(errorCode).c_str(), err); \
76  } while(0)
77 #else
78 #define debug_ifserr(err, func, ...) \
79  do { \
80  } while(0)
81 #endif
82 
96 {
97 public:
98  enum class Type {
99 #define XX(_name, _tag, _desc) _name,
101 #undef XX
102  MAX
103  };
104 
105  enum class Attribute {
106 #define XX(_tag, _comment) _tag,
108 #undef XX
109  MAX
110  };
111 
112  // The set of attributes
114 
118  struct Info {
119  Type type{};
120  Attributes attr{};
121  size_t maxNameLength{255};
122  size_t maxPathLength{255};
124  uint32_t volumeID{0};
126  uint32_t volumeSize{0};
127  uint32_t freeSpace{0};
128  TimeStamp creationTime{};
129 
131  {
132  }
133 
134  Info(char* namebuf, unsigned buflen) : name(namebuf, buflen)
135  {
136  }
137 
138  uint32_t used() const
139  {
140  return volumeSize - freeSpace;
141  }
142 
143  Info& operator=(const Info& rhs)
144  {
145  type = rhs.type;
146  partition = rhs.partition;
147  attr = rhs.attr;
148  volumeID = rhs.volumeID;
149  name.copy(rhs.name);
150  volumeSize = rhs.volumeSize;
151  freeSpace = rhs.freeSpace;
152  return *this;
153  }
154 
155  void clear()
156  {
157  *this = Info{};
158  }
159  };
160 
164  struct NameInfo : public Info {
165  public:
166  NameInfo() : Info(buffer, sizeof(buffer))
167  {
168  }
169 
170  private:
171  char buffer[256];
172  };
173 
177  virtual ~IFileSystem()
178  {
179  }
180 
185  virtual int mount() = 0;
186 
192  virtual int getinfo(Info& info) = 0;
193 
199  virtual int setProfiler(IProfiler* profiler)
200  {
201  return Error::NotImplemented;
202  }
203 
208  virtual String getErrorString(int err)
209  {
210  return Error::toString(err);
211  }
212 
219  virtual int setVolume(uint8_t index, IFileSystem* fileSystem)
220  {
221  return Error::NotSupported;
222  }
223 
230  virtual int opendir(const char* path, DirHandle& dir) = 0;
231 
240  virtual int readdir(DirHandle dir, Stat& stat) = 0;
241 
247  virtual int rewinddir(DirHandle dir) = 0;
248 
254  virtual int closedir(DirHandle dir) = 0;
255 
265  virtual int mkdir(const char* path) = 0;
266 
273  virtual int stat(const char* path, Stat* stat) = 0;
274 
281  virtual int fstat(FileHandle file, Stat* stat) = 0;
282 
295  virtual int fcontrol(FileHandle file, ControlCode code, void* buffer, size_t bufSize)
296  {
297  return Error::NotSupported;
298  }
299 
306  virtual FileHandle open(const char* path, OpenFlags flags) = 0;
307 
313  virtual int close(FileHandle file) = 0;
314 
322  virtual int read(FileHandle file, void* data, size_t size) = 0;
323 
331  virtual int write(FileHandle file, const void* data, size_t size) = 0;
332 
340  virtual int lseek(FileHandle file, int offset, SeekOrigin origin) = 0;
341 
347  virtual int eof(FileHandle file) = 0;
348 
354  virtual int32_t tell(FileHandle file) = 0;
355 
364  virtual int ftruncate(FileHandle file, size_t new_size) = 0;
365 
371  virtual int flush(FileHandle file) = 0;
372 
382  virtual int fsetxattr(FileHandle file, AttributeTag tag, const void* data, size_t size) = 0;
383 
392  virtual int fgetxattr(FileHandle file, AttributeTag tag, void* buffer, size_t size) = 0;
393 
402  virtual int fenumxattr(FileHandle file, AttributeEnumCallback callback, void* buffer, size_t bufsize) = 0;
403 
412  virtual int setxattr(const char* path, AttributeTag tag, const void* data, size_t size) = 0;
413 
422  virtual int getxattr(const char* path, AttributeTag tag, void* buffer, size_t size) = 0;
423 
430  virtual int rename(const char* oldpath, const char* newpath) = 0;
431 
437  virtual int remove(const char* path) = 0;
438 
444  virtual int fremove(FileHandle file) = 0;
445 
453  virtual int format() = 0;
454 
462  virtual int check()
463  {
464  return Error::NotImplemented;
465  }
466 };
467 
468 } // namespace IFS
469 
474 
479 
virtual int fcontrol(FileHandle file, ControlCode code, void *buffer, size_t bufSize)
Low-level and non-standard file control operations.
Definition: IFileSystem.h:295
Basic information about filing system.
Definition: IFileSystem.h:118
Attributes attr
Attribute flags.
Definition: IFileSystem.h:120
#define FILE_SYSTEM_ATTR_MAP(XX)
Attribute flags for filing system.
Definition: IFileSystem.h:54
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 check()
Perform a file system consistency check.
Definition: IFileSystem.h:462
virtual int fgetxattr(FileHandle file, AttributeTag tag, void *buffer, size_t size)=0
Get an extended attribute from an open file.
#define FILESYSTEM_TYPE_MAP(XX)
Four-character tag to identify type of filing system.
Definition: IFileSystem.h:43
virtual int close(FileHandle file)=0
close an open file
ControlCode
See IFS::IFileSystem::fcontrol
Definition: Control.h:31
virtual int mount()=0
Mount file system, performing any required initialisation.
virtual int fsetxattr(FileHandle file, AttributeTag tag, const void *data, size_t size)=0
Set an extended attribute on an open file.
virtual int eof(FileHandle file)=0
determine if current file position is at end of file
virtual int setVolume(uint8_t index, IFileSystem *fileSystem)
Set volume for mountpoint.
Definition: IFileSystem.h:219
virtual int rename(const char *oldpath, const char *newpath)=0
rename a file
Attribute
Definition: IFileSystem.h:105
Installable File System base class.
Definition: IFileSystem.h:95
virtual FileHandle open(const char *path, OpenFlags flags)=0
open a file by path
virtual int opendir(const char *path, DirHandle &dir)=0
open a directory for reading
int copy(const char *src, uint16_t srclen)
copies text from a source buffer into a name buffer
Definition: NameBuffer.h:95
virtual int mkdir(const char *path)=0
Create a directory.
struct ImplFileDir * DirHandle
Definition: IFileSystem.h:68
virtual int fenumxattr(FileHandle file, AttributeEnumCallback callback, void *buffer, size_t bufsize)=0
Enumerate attributes.
The String class.
Definition: WString.h:136
virtual int fremove(FileHandle file)=0
remove (delete) a file by handle
uint32_t volumeSize
Size of volume, in bytes.
Definition: IFileSystem.h:126
virtual int getxattr(const char *path, AttributeTag tag, void *buffer, size_t size)=0
Get an attribute from a file given its path.
virtual ~IFileSystem()
Filing system implementations should dismount and cleanup here.
Definition: IFileSystem.h:177
Definition: Delegate.h:20
NameInfo()
Definition: IFileSystem.h:166
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.
SeekOrigin
Stream/file seek origins.
Definition: SeekOrigin.h:18
virtual int closedir(DirHandle dir)=0
close a directory object
String toString(int err)
get text for an error code
uint32_t used() const
Definition: IFileSystem.h:138
int16_t FileHandle
File handle.
Definition: Stat.h:39
Type
Definition: IFileSystem.h:98
Filing system information with buffer for name.
Definition: IFileSystem.h:164
Definition: DirectoryTemplate.h:36
Manage IFS timestamps stored as an unsigned 32-bit value.
Definition: TimeStamp.h:35
virtual int read(FileHandle file, void *data, size_t size)=0
read content from a file and advance cursor
virtual int readdir(DirHandle dir, Stat &stat)=0
read a directory entry
virtual int ftruncate(FileHandle file, size_t new_size)=0
Truncate (reduce) the size of an open file.
NameBuffer name
Buffer for name.
Definition: IFileSystem.h:125
virtual int flush(FileHandle file)=0
flush any buffered data to physical media
Type type
The filing system type identifier.
Definition: IFileSystem.h:119
virtual int stat(const char *path, Stat *stat)=0
get file information
virtual int setProfiler(IProfiler *profiler)
Set profiler instance to enable debugging and performance assessment.
Definition: IFileSystem.h:199
uint32_t volumeID
Unique identifier for volume.
Definition: IFileSystem.h:124
File Status structure.
Definition: Stat.h:51
virtual int32_t tell(FileHandle file)=0
get current file position
void clear()
Definition: IFileSystem.h:155
uint32_t freeSpace
Available space, in bytes.
Definition: IFileSystem.h:127
virtual int format()=0
format the filing system
String toString(IFS::IFileSystem::Type type)
Get String for filesystem type.
Represents a flash partition.
Definition: Partition.h:78
Info & operator=(const Info &rhs)
Definition: IFileSystem.h:143
Filesystems may optionally provide performance statistics.
Definition: Profiler.h:29
AttributeTag
Identifies a specific attribute.
Definition: Attribute.h:45
virtual int rewinddir(DirHandle dir)=0
Reset directory read position to start.
virtual int fstat(FileHandle file, Stat *stat)=0
get file information
virtual int getinfo(Info &info)=0
get filing system information
Storage::Partition partition
Definition: IFileSystem.h:123
virtual int lseek(FileHandle file, int offset, SeekOrigin origin)=0
change file read/write position
XX(_name, _tag, _desc)
Info()
Definition: IFileSystem.h:130
Info(char *namebuf, unsigned buflen)
Definition: IFileSystem.h:134
defines a &#39;safe&#39; name buffer
Definition: NameBuffer.h:44
virtual String getErrorString(int err)
get the text for a returned error code
Definition: IFileSystem.h:208