Installable File System base class. More...

#include <IFileSystem.h>

Inheritance diagram for IFS::IFileSystem:

Classes
struct	Info
	Basic information about filing system. More...

Public Types
enum	Type { Type::XX, Type::MAX }

enum	Attribute { Attribute::XX, Attribute::MAX }

using	Attributes = BitSet< uint8_t, Attribute, size_t(Attribute::MAX)>

Public Member Functions
virtual	~IFileSystem ()
	Filing system implementations should dismount and cleanup here. More...

virtual int	mount ()=0
	Mount file system, performing any required initialisation. More...

virtual int	getinfo (Info &info)=0
	get filing system information More...

virtual String	getErrorString (int err)
	get the text for a returned error code More...

virtual int	opendir (const char *path, DirHandle &dir)=0
	open a directory for reading More...

virtual int	fopendir (const Stat *stat, DirHandle &dir)
	open a directory for reading More...

virtual int	readdir (DirHandle dir, Stat &stat)=0
	read a directory entry More...

virtual int	rewinddir (DirHandle dir)=0
	Reset directory read position to start. More...

virtual int	closedir (DirHandle dir)=0
	close a directory object More...

virtual int	mkdir (const char *path)=0
	Create a directory. More...

virtual int	stat (const char path, Stat stat)=0
	get file information More...

virtual int	fstat (FileHandle file, Stat *stat)=0
	get file information More...

virtual int	fcontrol (FileHandle file, ControlCode code, void *buffer, size_t bufSize)
	Low-level and non-standard file control operations. More...

virtual FileHandle	open (const char *path, OpenFlags flags)=0
	open a file by name/path More...

virtual FileHandle	fopen (const Stat &stat, OpenFlags flags)=0
	open a file from it's stat structure More...

virtual int	close (FileHandle file)=0
	close an open file More...

virtual int	read (FileHandle file, void *data, size_t size)=0
	read content from a file and advance cursor More...

virtual int	write (FileHandle file, const void *data, size_t size)=0
	write content to a file at current position and advance cursor More...

virtual int	lseek (FileHandle file, int offset, SeekOrigin origin)=0
	change file read/write position More...

virtual int	eof (FileHandle file)=0
	determine if current file position is at end of file More...

virtual int32_t	tell (FileHandle file)=0
	get current file position More...

virtual int	ftruncate (FileHandle file, size_t new_size)=0
	Truncate (reduce) the size of an open file. More...

virtual int	flush (FileHandle file)=0
	flush any buffered data to physical media More...

virtual int	setacl (FileHandle file, const ACL &acl)=0
	Set access control information for file. More...

virtual int	setattr (const char *path, FileAttributes attr)=0
	Set file attributes. More...

virtual int	settime (FileHandle file, time_t mtime)=0
	Set modificatino tiem for file. More...

virtual int	setcompression (FileHandle file, const Compression &compression)=0
	Set file compression information. More...

virtual int	rename (const char oldpath, const char newpath)=0
	rename a file More...

virtual int	remove (const char *path)=0
	remove (delete) a file by path More...

virtual int	fremove (FileHandle file)=0
	remove (delete) a file by handle More...

virtual int	format ()=0
	format the filing system More...

virtual int	check ()
	Perform a file system consistency check. More...

Detailed Description

Installable File System base class.

Note: The 'I' implies Installable but could be for Interface :-)

Construction and initialisation of a filing system is implementation-dependent so there are no methods here for that.

Methods are defined as virtual abstract unless we actually have a default base implementation. Whilst some methods could just return Error::NotImplemented by default, keeping them abstract forces all file system implementations to consider them so provides an extra check for completeness.

Member Typedef Documentation

◆ Attributes

using IFS::IFileSystem::Attributes = BitSet<uint8_t, Attribute, size_t(Attribute::MAX)>

Member Enumeration Documentation

◆ Attribute

enum IFS::IFileSystem::Attribute

strong

Enumerator
XX
MAX

◆ Type

enum IFS::IFileSystem::Type

strong

Enumerator
XX
MAX

Constructor & Destructor Documentation

◆ ~IFileSystem()

virtual IFS::IFileSystem::~IFileSystem ( )

inlinevirtual

Filing system implementations should dismount and cleanup here.

Member Function Documentation

◆ check()

virtual int IFS::IFileSystem::check ( )

inlinevirtual

Perform a file system consistency check.

Return values

int	error code

Note: if possible, issues should be resolved. Returns 0 if file system checked out OK. Otherwise there were issues: < 0 for unrecoverable errors,

0 for recoverable errors.

Reimplemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::SPIFFS::FileSystem, IFS::Host::FileSystem, and IFS::HYFS::FileSystem.

◆ close()

virtual int IFS::IFileSystem::close ( FileHandle file )

pure virtual

close an open file

Parameters

file	handle to open file

Return values

int	error code

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ closedir()

virtual int IFS::IFileSystem::closedir ( DirHandle dir )

pure virtual

close a directory object

Parameters

dir	directory to close

Return values

int	error code

Implemented in IFS::FWFS::FileSystem, IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, IFS::Gdb::FileSystem, and IFS::Host::FileSystem.

◆ eof()

virtual int IFS::IFileSystem::eof ( FileHandle file )

pure virtual

determine if current file position is at end of file

Parameters

file	handle to open file

Return values

int	0 - not EOF, > 0 - at EOF, < 0 - error

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ fcontrol()

virtual int IFS::IFileSystem::fcontrol	(	FileHandle	file,
		ControlCode	code,
		void *	buffer,
		size_t	bufSize
	)

inlinevirtual

Low-level and non-standard file control operations.

Parameters

file
code	FCNTL_XXX code
buffer	Input/Output buffer
bufSize	Size of buffer

Return values

int	error code or, on success, data size

To simplify usage the same buffer is used for both input and output. Only the size of the buffer is provided. If a specific FCNTL code requires more information then it will be contained within the provided data.

Reimplemented in IFS::FWFS::FileSystem, and IFS::HYFS::FileSystem.

◆ flush()

virtual int IFS::IFileSystem::flush ( FileHandle file )

pure virtual

flush any buffered data to physical media

Parameters

file	handle to open file

Return values

int	error code

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ fopen()

virtual FileHandle IFS::IFileSystem::fopen	(	const Stat &	stat,
		OpenFlags	flags
	)

pure virtual

open a file from it's stat structure

Parameters

stat	obtained from readdir()
flags	opens for opening file

Return values

FileHandle file handle or error code

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ fopendir()

virtual int IFS::IFileSystem::fopendir	(	const Stat *	stat,
		DirHandle &	dir
	)

inlinevirtual

open a directory for reading

Parameters

stat	identifies directory to open. nullptr is interpreted as root directory
dir	returns a pointer to the directory object

Return values

int	error code

Reimplemented in IFS::FWFS::FileSystem.

◆ format()

virtual int IFS::IFileSystem::format ( )

pure virtual

format the filing system

Return values

int	error code

Note: this does a default format, returning file system to a fresh state The filing system implementation may define more specialised methods which can be called directly.

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ fremove()

virtual int IFS::IFileSystem::fremove ( FileHandle file )

pure virtual

remove (delete) a file by handle

Parameters

file	handle to open file

Return values

int	error code

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ fstat()

virtual int IFS::IFileSystem::fstat	(	FileHandle	file,
		Stat *	stat
	)

pure virtual

get file information

Parameters

file	handle to open file
stat	structure to return information in, may be null

Return values

int	error code

Implemented in IFS::FWFS::FileSystem, IFS::SPIFFS::FileSystem, IFS::Gdb::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ ftruncate()

virtual int IFS::IFileSystem::ftruncate	(	FileHandle	file,
		size_t	new_size
	)

pure virtual

Truncate (reduce) the size of an open file.

Parameters

file	Open file handle, must have Write access
newSize

Return values

int	Error code

Note: In POSIX ftruncate() can also make the file bigger, however SPIFFS can only reduce the file size and will return an error if newSize > fileSize

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ getErrorString()

virtual String IFS::IFileSystem::getErrorString ( int err )

inlinevirtual

get the text for a returned error code

Return values

String

Reimplemented in IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, IFS::Host::FileSystem, and IFS::Gdb::FileSystem.

◆ getinfo()

virtual int IFS::IFileSystem::getinfo ( Info & info )

pure virtual

get filing system information

Parameters

info	structure to read information into

Return values

int	error code

Implemented in IFS::FWFS::FileSystem, IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, IFS::Host::FileSystem, and IFS::Gdb::FileSystem.

◆ lseek()

virtual int IFS::IFileSystem::lseek	(	FileHandle	file,
		int	offset,
		SeekOrigin	origin
	)

pure virtual

change file read/write position

Parameters

file	handle to open file
offset	position relative to origin
origin	where to seek from (start/end or current position)

Return values

int	current position or error code

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ mkdir()

virtual int IFS::IFileSystem::mkdir ( const char * path )

pure virtual

Create a directory.

Parameters

path	Path to directory

Return values

int	error code

Only the final directory in the path is guaranteed to be created. Usually, this call will fail if intermediate directories are not present. Use makedirs() for this purpose.

Implemented in IFS::FWFS::FileSystem, IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, IFS::Gdb::FileSystem, and IFS::Host::FileSystem.

◆ mount()

virtual int IFS::IFileSystem::mount ( )

pure virtual

Mount file system, performing any required initialisation.

Return values

error code

Implemented in IFS::FWFS::FileSystem, IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, IFS::Host::FileSystem, and IFS::Gdb::FileSystem.

◆ open()

virtual FileHandle IFS::IFileSystem::open	(	const char *	path,
		OpenFlags	flags
	)

pure virtual

open a file by name/path

Parameters

path	full path to file
flags	opens for opening file

Return values

FileHandle file handle or error code

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ opendir()

virtual int IFS::IFileSystem::opendir	(	const char *	path,
		DirHandle &	dir
	)

pure virtual

open a directory for reading

Parameters

path	path to directory. nullptr is interpreted as root directory
dir	returns a pointer to the directory object

Return values

int	error code

Implemented in IFS::FWFS::FileSystem, IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, IFS::Host::FileSystem, and IFS::Gdb::FileSystem.

◆ read()

virtual int IFS::IFileSystem::read	(	FileHandle	file,
		void *	data,
		size_t	size
	)

pure virtual

read content from a file and advance cursor

Parameters

file	handle to open file
data	buffer to write into
size	size of file buffer, maximum number of bytes to read

Return values

int	number of bytes read or error code

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ readdir()

virtual int IFS::IFileSystem::readdir	(	DirHandle	dir,
		Stat &	stat
	)

pure virtual

read a directory entry

Parameters

dir
stat

Return values

int	error code

Note: File system allocates entries structure as it usually needs to track other information. It releases memory when closedir() is called.

Implemented in IFS::FWFS::FileSystem, IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, IFS::Gdb::FileSystem, and IFS::Host::FileSystem.

◆ remove()

virtual int IFS::IFileSystem::remove ( const char * path )

pure virtual

remove (delete) a file by path

Parameters

path

Return values

int	error code

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ rename()

virtual int IFS::IFileSystem::rename	(	const char *	oldpath,
		const char *	newpath
	)

pure virtual

rename a file

Parameters

oldpath
newpath

Return values

int	error code

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ rewinddir()

virtual int IFS::IFileSystem::rewinddir ( DirHandle dir )

pure virtual

Reset directory read position to start.

Parameters

dir

Return values

int	error code

Implemented in IFS::FWFS::FileSystem, IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, IFS::Gdb::FileSystem, and IFS::Host::FileSystem.

◆ setacl()

virtual int IFS::IFileSystem::setacl	(	FileHandle	file,
		const ACL &	acl
	)

pure virtual

Set access control information for file.

Parameters

file	handle to open file
acl

Return values

int	error code

Implemented in IFS::FWFS::FileSystem, IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, IFS::Gdb::FileSystem, and IFS::Host::FileSystem.

◆ setattr()

virtual int IFS::IFileSystem::setattr	(	const char *	path,
		FileAttributes	attr
	)

pure virtual

Set file attributes.

Parameters

path	Full path to file
attr

Return values

int	error code

Implemented in IFS::FWFS::FileSystem, IFS::SPIFFS::FileSystem, IFS::Gdb::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ setcompression()

virtual int IFS::IFileSystem::setcompression	(	FileHandle	file,
		const Compression &	compression
	)

pure virtual

Set file compression information.

Parameters

file
compression

Return values

int	error code

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ settime()

virtual int IFS::IFileSystem::settime	(	FileHandle	file,
		time_t	mtime
	)

pure virtual

Set modificatino tiem for file.

Parameters

file	handle to open file, must have write access

Return values

int	error code

Note: any subsequent writes to file will reset this to current time

Implemented in IFS::FWFS::FileSystem, IFS::SPIFFS::FileSystem, IFS::Gdb::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ stat()

virtual int IFS::IFileSystem::stat	(	const char *	path,
		Stat *	stat
	)

pure virtual

get file information

Parameters

path	name or path of file
s	structure to return information in, may be null to do a simple file existence check

Return values

int	error code

Implemented in IFS::FWFS::FileSystem, IFS::SPIFFS::FileSystem, IFS::Gdb::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ tell()

virtual int32_t IFS::IFileSystem::tell ( FileHandle file )

pure virtual

get current file position

Parameters

file	handle to open file

Return values

int32_t current position relative to start of file, or error code

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ write()

virtual int IFS::IFileSystem::write	(	FileHandle	file,
		const void *	data,
		size_t	size
	)

pure virtual

write content to a file at current position and advance cursor

Parameters

file	handle to open file
data	buffer to read from
size	number of bytes to write

Return values

int	number of bytes written or error code

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::SPIFFS::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

The documentation for this class was generated from the following file:

IFileSystem.h

Classes

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ Attributes

Member Enumeration Documentation

◆ Attribute

◆ Type

Constructor & Destructor Documentation

◆ ~IFileSystem()

Member Function Documentation

◆ check()

◆ close()

◆ closedir()

◆ eof()

◆ fcontrol()

◆ flush()

◆ fopen()

◆ fopendir()

◆ format()

◆ fremove()

◆ fstat()

◆ ftruncate()

◆ getErrorString()

◆ getinfo()

◆ lseek()

◆ mkdir()

◆ mount()

◆ open()

◆ opendir()

◆ read()

◆ readdir()

◆ remove()

◆ rename()

◆ rewinddir()

◆ setacl()

◆ setattr()

◆ setcompression()

◆ settime()

◆ stat()

◆ tell()

◆ write()