Core/FileSystem.h
Go to the documentation of this file.
1 /****
2  * Sming Framework Project - Open Source framework for high efficiency native ESP8266 development.
3  * Created 2015 by Skurydin Alexey
4  * http://github.com/SmingHub/Sming
5  * All files of the Sming Core are provided under the LGPL v3 license.
6  *
7  * FileSystem.h
8  *
9  ****/
10 
16 #pragma once
17 
18 #include <IFS/Helpers.h>
19 #include <IFS/File.h>
20 #include <IFS/Directory.h>
21 #include <Spiffs.h>
22 #include "WVector.h"
23 
34 constexpr int FS_OK = IFS::FS_OK;
35 
39 
40 namespace SmingInternal
41 {
51 
52 } // namespace SmingInternal
53 
54 class File : public IFS::File
55 {
56 public:
58  {
59  }
60 };
61 
66 class Directory : public IFS::Directory
67 {
68 public:
70  {
71  }
72 };
73 
74 // Various file flag combinations
82 
83 /*
84  * Boilerplate check for file function wrappers to catch undefined filesystem.
85  */
86 #define CHECK_FS(_method) \
87  auto fileSystem = static_cast<IFS::FileSystem*>(SmingInternal::activeFileSystem); \
88  if(fileSystem == nullptr) { \
89  debug_e("ERROR in %s(): No active file system", __FUNCTION__); \
90  return FileHandle(IFS::Error::NoFileSystem); \
91  }
92 
98 {
99  if(SmingInternal::activeFileSystem == nullptr) {
100  debug_e("ERROR: No active file system");
101  }
103 }
104 
113 void fileSetFileSystem(IFS::IFileSystem* fileSystem);
114 
115 inline void fileFreeFileSystem()
116 {
117  fileSetFileSystem(nullptr);
118 }
119 
124 
129 bool fwfs_mount();
130 
135 bool fwfs_mount(Storage::Partition partition);
136 
142 template <typename T> inline FileHandle fileOpen(const T& path, FileOpenFlags flags = File::ReadOnly)
143 {
144  CHECK_FS(open)
145  return fileSystem->open(path, flags);
146 }
147 
152 inline int fileClose(FileHandle file)
153 {
154  CHECK_FS(close)
155  return fileSystem->close(file);
156 }
157 
164 inline int fileWrite(FileHandle file, const void* data, size_t size)
165 {
166  CHECK_FS(write);
167  return fileSystem->write(file, data, size);
168 }
169 
174 inline int fileTouch(FileHandle file)
175 {
176  return fileWrite(file, nullptr, 0);
177 }
178 
185 inline int fileRead(FileHandle file, void* data, size_t size)
186 {
187  CHECK_FS(read)
188  return fileSystem->read(file, data, size);
189 }
190 
197 inline int fileSeek(FileHandle file, int offset, SeekOrigin origin)
198 {
199  CHECK_FS(seek)
200  return fileSystem->lseek(file, offset, origin);
201 }
202 
207 inline bool fileIsEOF(FileHandle file)
208 {
209  auto fileSystem = getFileSystem();
210  return fileSystem ? (fileSystem->eof(file) != 0) : true;
211 }
212 
217 inline int fileTell(FileHandle file)
218 {
219  CHECK_FS(tell)
220  return fileSystem->tell(file);
221 }
222 
227 inline int fileFlush(FileHandle file)
228 {
229  CHECK_FS(flush)
230  return fileSystem->flush(file);
231 }
232 
237 inline String fileGetErrorString(int err)
238 {
239  auto fileSystem = getFileSystem();
240  if(fileSystem == nullptr) {
241  return IFS::Error::toString(err);
242  }
243  return fileSystem->getErrorString(err);
244 }
245 
254 template <typename TFileName> inline int fileSetContent(const TFileName& fileName, const char* content, size_t length)
255 {
256  CHECK_FS(setContent)
257  return fileSystem->setContent(fileName, content, length);
258 }
259 
260 template <typename TFileName, typename TContent> inline int fileSetContent(const TFileName& fileName, TContent content)
261 {
262  CHECK_FS(setContent)
263  return fileSystem->setContent(fileName, content);
264 }
265 
270 template <typename TFileName> inline uint32_t fileGetSize(const TFileName& fileName)
271 {
272  auto fileSystem = getFileSystem();
273  return fileSystem ? fileSystem->getSize(fileName) : 0;
274 }
275 
283 inline int fileTruncate(FileHandle file, size_t newSize)
284 {
285  CHECK_FS(truncate);
286  return fileSystem->ftruncate(file, newSize);
287 }
288 
293 inline int fileTruncate(FileHandle file)
294 {
295  CHECK_FS(truncate);
296  return fileSystem->ftruncate(file);
297 }
298 
306 template <typename TFileName> int fileTruncate(const TFileName& fileName, size_t newSize)
307 {
308  CHECK_FS(truncate);
309  return fileSystem->truncate(fileName, newSize);
310 }
311 
317 inline int fileRename(const char* oldName, const char* newName)
318 {
319  CHECK_FS(rename)
320  return fileSystem->rename(oldName, newName);
321 }
322 
323 inline int fileRename(const String& oldName, const String& newName)
324 {
325  return fileRename(oldName.c_str(), newName.c_str());
326 }
327 
334 
342 template <typename TFileName> String fileGetContent(const TFileName& fileName)
343 {
344  auto fileSystem = getFileSystem();
345  return fileSystem ? fileSystem->getContent(fileName) : nullptr;
346 }
347 
359 template <typename TFileName> inline size_t fileGetContent(const TFileName& fileName, char* buffer, size_t bufSize)
360 {
361  auto fileSystem = getFileSystem();
362  return fileSystem ? fileSystem->getContent(fileName, buffer, bufSize) : 0;
363 }
364 
365 template <typename TFileName> inline size_t fileGetContent(const TFileName& fileName, char* buffer)
366 {
367  auto fileSystem = getFileSystem();
368  return fileSystem ? fileSystem->getContent(fileName, buffer) : 0;
369 }
370 
376 inline int fileStats(const char* fileName, FileStat& stat)
377 {
378  CHECK_FS(stat)
379  return fileSystem->stat(fileName, &stat);
380 }
381 
382 inline int fileStats(const String& fileName, FileStat& stat)
383 {
384  return fileStats(fileName.c_str(), stat);
385 }
386 
392 inline int fileStats(FileHandle file, FileStat& stat)
393 {
394  CHECK_FS(fstat)
395  return fileSystem->fstat(file, &stat);
396 }
397 
402 inline int fileDelete(const char* fileName)
403 {
404  CHECK_FS(remove)
405  return fileSystem->remove(fileName);
406 }
407 
408 inline int fileDelete(const String& fileName)
409 {
410  return fileDelete(fileName.c_str());
411 }
412 
417 inline int fileDelete(FileHandle file)
418 {
419  CHECK_FS(fremove)
420  return fileSystem->fremove(file);
421 }
422 
427 inline bool fileExist(const char* fileName)
428 {
429  CHECK_FS(stat)
430  FileStat stat;
431  return fileSystem->stat(fileName, &stat) >= 0 && !stat.attr[FileAttribute::Directory];
432 }
433 
434 inline bool fileExist(const String& fileName)
435 {
436  return fileExist(fileName.c_str());
437 }
438 
443 inline bool dirExist(const char* dirName)
444 {
445  CHECK_FS(stat)
446  FileStat stat;
447  return fileSystem->stat(dirName, &stat) >= 0 && stat.attr[FileAttribute::Directory];
448 }
449 
450 inline bool dirExist(const String& dirName)
451 {
452  return dirExist(dirName.c_str());
453 }
454 
461 inline int fileOpenDir(const char* dirName, DirHandle& dir)
462 {
463  CHECK_FS(opendir)
464  return fileSystem->opendir(dirName, dir);
465 }
466 
467 inline int fileOpenDir(const String& dirName, DirHandle& dir)
468 {
469  return fileOpenDir(dirName.c_str(), dir);
470 }
471 
472 inline int fileOpenRootDir(DirHandle& dir)
473 {
474  return fileOpenDir(nullptr, dir);
475 }
476 
481 inline int fileCloseDir(DirHandle dir)
482 {
483  CHECK_FS(closedir)
484  return fileSystem->closedir(dir);
485 }
486 
492 inline int fileReadDir(DirHandle dir, FileStat& stat)
493 {
494  CHECK_FS(readdir)
495  return fileSystem->readdir(dir, stat);
496 }
497 
502 inline int fileRewindDir(DirHandle dir)
503 {
504  CHECK_FS(rewinddir)
505  return fileSystem->rewinddir(dir);
506 }
507 
512 {
513  CHECK_FS(getinfo)
514  return fileSystem->getinfo(info);
515 }
516 
521 
525 inline int fileSystemFormat()
526 {
527  CHECK_FS(format)
528  return fileSystem->format();
529 }
530 
534 inline int fileSystemCheck()
535 {
536  CHECK_FS(check)
537  return fileSystem->check();
538 }
539 
545 inline int fileSetACL(FileHandle file, const IFS::ACL& acl)
546 {
547  CHECK_FS(setacl)
548  return fileSystem->setacl(file, acl);
549 }
550 
557 inline int fileSetAttr(const char* filename, FileAttributes attr)
558 {
559  CHECK_FS(setattr)
560  return fileSystem->setattr(filename, attr);
561 }
562 
563 inline int fileSetAttr(const String& filename, FileAttributes attr)
564 {
565  return fileSetAttr(filename.c_str(), attr);
566 }
574 inline int fileSetTime(FileHandle file, time_t mtime)
575 {
576  CHECK_FS(settime)
577  return fileSystem->settime(file, mtime);
578 }
579 
Definition: Core/FileSystem.h:40
Basic information about filing system.
Definition: IFileSystem.h:118
version of Stat with integrated name buffer
Definition: Stat.h:97
#define CHECK_FS(_method)
Definition: Core/FileSystem.h:86
IFS::FileSystem::Type fileSystemType()
Get the type of file system currently mounted (if any)
constexpr FileOpenFlags eFO_Truncate
Definition: Core/FileSystem.h:80
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 remove(const char *path)=0
remove (delete) a file by path
virtual int check()
Perform a file system consistency check.
Definition: IFileSystem.h:462
IFS::FileHandle file_t
<
Definition: Core/FileSystem.h:24
virtual int close(FileHandle file)=0
close an open file
int fileTruncate(FileHandle file, size_t newSize)
Truncate (reduce) the size of an open file.
Definition: Core/FileSystem.h:283
FileAttribute
Definition: FileAttributes.h:46
BitSet< uint8_t, OpenFlag, size_t(OpenFlag::MAX)> OpenFlags
Definition: OpenFlags.h:50
const char * c_str() const
Get a constant (un-modifiable) pointer to String content.
Definition: WString.h:641
int fileSetTime(FileHandle file, time_t mtime)
Set access control information for file.
Definition: Core/FileSystem.h:574
Directory stream class.
Definition: Core/FileSystem.h:66
virtual int eof(FileHandle file)=0
determine if current file position is at end of file
virtual int rename(const char *oldpath, const char *newpath)=0
rename a file
static constexpr OpenFlags Append
Definition: File.h:39
Installable File System base class.
Definition: IFileSystem.h:95
virtual FileHandle open(const char *path, OpenFlags flags)=0
open a file by path
FileAttributes attr
Definition: Stat.h:58
SEEK_SET: Start of file.
int fileSeek(FileHandle file, int offset, SeekOrigin origin)
Position file cursor.
Definition: Core/FileSystem.h:197
static constexpr OpenFlags ReadWrite
Definition: File.h:37
constexpr SeekOrigin eSO_CurrentPos
Definition: Core/FileSystem.h:37
bool fileExist(const char *fileName)
Check if a file exists on file system.
Definition: Core/FileSystem.h:427
int fileClose(FileHandle file)
Clode file.
Definition: Core/FileSystem.h:152
virtual int opendir(const char *path, DirHandle &dir)=0
open a directory for reading
static constexpr OpenFlags ReadOnly
Definition: File.h:35
int fileRename(const char *oldName, const char *newName)
Rename file.
Definition: Core/FileSystem.h:317
String fileGetErrorString(int err)
get the text for a returned error code
Definition: Core/FileSystem.h:237
String fileGetContent(const TFileName &fileName)
Read content of a file.
Definition: Core/FileSystem.h:342
BitSet< uint8_t, FileAttribute, size_t(FileAttribute::MAX)> FileAttributes
File attributes are stored as a bitmask.
Definition: FileAttributes.h:56
Wraps up all file access methods.
Definition: File.h:29
struct ImplFileDir * DirHandle
Definition: IFileSystem.h:68
int fileRewindDir(DirHandle dir)
Rewind to start of directory entries.
Definition: Core/FileSystem.h:502
constexpr SeekOrigin eSO_FileStart
Definition: Core/FileSystem.h:36
The String class.
Definition: WString.h:136
int fileSetACL(FileHandle file, const IFS::ACL &acl)
Set access control information.
Definition: Core/FileSystem.h:545
int fileCloseDir(DirHandle dir)
close a directory object
Definition: Core/FileSystem.h:481
virtual int fremove(FileHandle file)=0
remove (delete) a file by handle
Installable File System base class.
Definition: Components/IFS/src/include/IFS/FileSystem.h:39
SeekOrigin SeekOriginFlags
Definition: Core/FileSystem.h:25
Wrapper class for enumerating a directory.
Definition: Directory.h:31
bool fileMountFileSystem(IFS::IFileSystem *fs)
Mount a constructed filesystem with debug messages.
SEEK_END: End of file.
bool fwfs_mount()
Mount the first available FWFS volume.
SeekOrigin
Stream/file seek origins.
Definition: SeekOrigin.h:18
virtual int closedir(DirHandle dir)=0
close a directory object
static constexpr OpenFlags WriteOnly
Definition: File.h:36
uint32_t fileGetSize(const TFileName &fileName)
Get size of file.
Definition: Core/FileSystem.h:270
int fileSetAttr(const char *filename, FileAttributes attr)
Definition: Core/FileSystem.h:557
String toString(int err)
get text for an error code
int fileOpenDir(const char *dirName, DirHandle &dir)
Open a named directory for reading.
Definition: Core/FileSystem.h:461
int16_t FileHandle
File handle.
Definition: Stat.h:39
Type
Definition: IFileSystem.h:98
Definition: DirectoryTemplate.h:36
SEEK_CUR: Current position in file.
virtual int read(FileHandle file, void *data, size_t size)=0
read content from a file and advance cursor
#define SMING_DEPRECATED
Definition: sming_attr.h:30
virtual int readdir(DirHandle dir, Stat &stat)=0
read a directory entry
#define debug_e(fmt,...)
Definition: debug_progmem.h:77
virtual int ftruncate(FileHandle file, size_t new_size)=0
Truncate (reduce) the size of an open file.
int fileSetContent(const TFileName &fileName, const char *content, size_t length)
Create or replace file with defined content.
Definition: Core/FileSystem.h:254
File()
Definition: Core/FileSystem.h:57
int fileStats(const char *fileName, FileStat &stat)
Get file statistics.
Definition: Core/FileSystem.h:376
Vector< String > fileList()
Get list of files on file system.
int fileWrite(FileHandle file, const void *data, size_t size)
Write to file.
Definition: Core/FileSystem.h:164
int fileTell(FileHandle file)
Get position in file.
Definition: Core/FileSystem.h:217
IFS::FileSystem * getFileSystem()
Get the currently active file system, if any.
Definition: Core/FileSystem.h:97
FileHandle fileOpen(const T &path, FileOpenFlags flags=File::ReadOnly)
Open file by path.
Definition: Core/FileSystem.h:142
IFS::DirHandle DirHandle
Definition: Core/FileSystem.h:27
int fileTouch(FileHandle file)
Update file modification time.
Definition: Core/FileSystem.h:174
virtual int flush(FileHandle file)=0
flush any buffered data to physical media
virtual int stat(const char *path, Stat *stat)=0
get file information
File Status structure.
Definition: Stat.h:51
virtual int32_t tell(FileHandle file)=0
get current file position
Manage a set of bit values using enumeration.
Definition: BitSet.h:43
constexpr int FS_OK
Definition: Core/FileSystem.h:34
int fileFlush(FileHandle file)
Flush pending writes.
Definition: Core/FileSystem.h:227
constexpr FileOpenFlags eFO_WriteOnly
Definition: Core/FileSystem.h:76
constexpr FileOpenFlags eFO_ReadOnly
Definition: Core/FileSystem.h:75
int fileOpenRootDir(DirHandle &dir)
Definition: Core/FileSystem.h:472
bool dirExist(const char *dirName)
Check if a directory exists on file system.
Definition: Core/FileSystem.h:443
virtual int format()=0
format the filing system
int fileRead(FileHandle file, void *data, size_t size)
Read from file.
Definition: Core/FileSystem.h:185
Represents a flash partition.
Definition: Partition.h:78
int fileDelete(const char *fileName)
Delete file.
Definition: Core/FileSystem.h:402
int fileReadDir(DirHandle dir, FileStat &stat)
Read a directory entry.
Definition: Core/FileSystem.h:492
void fileSetFileSystem(IFS::IFileSystem *fileSystem)
Sets the currently active file system.
IFS::FileSystem * activeFileSystem
Global file system instance.
Definition: Access.h:34
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
virtual int lseek(FileHandle file, int offset, SeekOrigin origin)=0
change file read/write position
static constexpr OpenFlags CreateNewAlways
Definition: File.h:41
constexpr FileOpenFlags eFO_CreateNewAlways
Definition: Core/FileSystem.h:81
constexpr FileOpenFlags eFO_Append
Definition: Core/FileSystem.h:79
void fileFreeFileSystem()
Definition: Core/FileSystem.h:115
IFS::FileHandle FileHandle
Definition: Core/FileSystem.h:26
int fileSystemFormat()
Format the active file system.
Definition: Core/FileSystem.h:525
constexpr SeekOrigin eSO_FileEnd
Definition: Core/FileSystem.h:38
Definition: Core/FileSystem.h:54
int fileGetSystemInfo(IFS::FileSystem::Info &info)
Get basic file system information.
Definition: Core/FileSystem.h:511
Directory()
Definition: Core/FileSystem.h:69
constexpr ErrorCode FS_OK
Definition: Error.h:128
bool fileIsEOF(FileHandle file)
Check if at end of file.
Definition: Core/FileSystem.h:207
constexpr FileOpenFlags eFO_ReadWrite
Definition: Core/FileSystem.h:77
constexpr FileOpenFlags eFO_CreateIfNotExist
Definition: Core/FileSystem.h:78
OpenFlag
Definition: OpenFlags.h:42
static constexpr OpenFlags Create
Definition: File.h:38
int fileSystemCheck()
Perform a consistency check/repair on the active file system.
Definition: Core/FileSystem.h:534
static constexpr OpenFlags Truncate
Definition: File.h:40
virtual String getErrorString(int err)
get the text for a returned error code
Definition: IFileSystem.h:208