Access file system. More...
Namespaces | |
SmingInternal | |
IFS | |
IFS::Error | |
Classes | |
class | File |
class | Directory |
Directory stream class. More... | |
Macros | |
#define | CHECK_FS(_method) |
#define | IFS_ERROR_MAP(XX) |
IFS return codes. More... | |
#define | XX(tag, text) tag, |
#define | XX(tag, text) constexpr int tag{-int(Value::tag)}; |
#define | FILESYSTEM_TYPE_MAP(XX) |
Four-character tag to identify type of filing system. More... | |
#define | FILE_SYSTEM_ATTR_MAP(XX) |
Attribute flags for filing system. More... | |
Typedefs | |
using | file_t = IFS::FileHandle |
< More... | |
typedef SeekOrigin | SeekOriginFlags |
using | FileHandle = IFS::FileHandle |
using | DirHandle = IFS::DirHandle |
using | FileOpenFlag = IFS::OpenFlag |
using | FileOpenFlags = IFS::OpenFlags |
using | FileAttribute = IFS::FileAttribute |
using | FileAttributes = IFS::FileAttributes |
using | FileStat = IFS::Stat |
using | FileNameStat = IFS::NameStat |
using | IFS::ErrorCode = int |
Enumerations | |
enum | IFS::Error::Value { IFS::Error::Value::XX, IFS::Error::Value::MAX } |
Functions | |
IFS::FileSystem * | getFileSystem () |
Get the currently active file system, if any. More... | |
void | fileSetFileSystem (IFS::IFileSystem *fileSystem) |
Sets the currently active file system. More... | |
void | fileFreeFileSystem () |
bool | fileMountFileSystem (IFS::IFileSystem *fs) |
Mount a constructed filesystem with debug messages. More... | |
bool | fwfs_mount () |
Mount the first available FWFS volume. More... | |
bool | fwfs_mount (Storage::Partition partition) |
Mount SPIFFS volume from a specific partition. More... | |
template<typename T > | |
FileHandle | fileOpen (const T &path, FileOpenFlags flags=File::ReadOnly) |
Open file by path. More... | |
int | fileClose (FileHandle file) |
Clode file. More... | |
int | fileWrite (FileHandle file, const void *data, size_t size) |
Write to file. More... | |
int | fileTouch (FileHandle file) |
Update file modification time. More... | |
int | fileRead (FileHandle file, void *data, size_t size) |
Read from file. More... | |
int | fileSeek (FileHandle file, int offset, SeekOrigin origin) |
Position file cursor. More... | |
bool | fileIsEOF (FileHandle file) |
Check if at end of file. More... | |
int | fileTell (FileHandle file) |
Get position in file. More... | |
int | fileFlush (FileHandle file) |
Flush pending writes. More... | |
String | fileGetErrorString (int err) |
get the text for a returned error code More... | |
template<typename TFileName > | |
int | fileSetContent (const TFileName &fileName, const char *content, size_t length) |
Create or replace file with defined content. More... | |
template<typename TFileName , typename TContent > | |
int | fileSetContent (const TFileName &fileName, TContent content) |
template<typename TFileName > | |
uint32_t | fileGetSize (const TFileName &fileName) |
Get size of file. More... | |
int | fileTruncate (FileHandle file, size_t newSize) |
Truncate (reduce) the size of an open file. More... | |
int | fileTruncate (FileHandle file) |
Truncate an open file at the current cursor position. More... | |
template<typename TFileName > | |
int | fileTruncate (const TFileName &fileName, size_t newSize) |
Truncate (reduce) the size of a file. More... | |
int | fileRename (const char *oldName, const char *newName) |
Rename file. More... | |
int | fileRename (const String &oldName, const String &newName) |
Vector< String > | fileList () |
Get list of files on file system. More... | |
template<typename TFileName > | |
String | fileGetContent (const TFileName &fileName) |
Read content of a file. More... | |
template<typename TFileName > | |
size_t | fileGetContent (const TFileName &fileName, char *buffer, size_t bufSize) |
Read content of a file. More... | |
template<typename TFileName > | |
size_t | fileGetContent (const TFileName &fileName, char *buffer) |
int | fileStats (const char *fileName, FileStat &stat) |
Get file statistics. More... | |
int | fileStats (const String &fileName, FileStat &stat) |
int | fileStats (FileHandle file, FileStat &stat) |
int | fileDelete (const char *fileName) |
Delete file. More... | |
int | fileDelete (const String &fileName) |
int | fileDelete (FileHandle file) |
Delete file. More... | |
bool | fileExist (const char *fileName) |
Check if a file exists on file system. More... | |
bool | fileExist (const String &fileName) |
bool | dirExist (const char *dirName) |
Check if a directory exists on file system. More... | |
bool | dirExist (const String &dirName) |
int | fileOpenDir (const char *dirName, DirHandle &dir) |
Open a named directory for reading. More... | |
int | fileOpenDir (const String &dirName, DirHandle &dir) |
int | fileOpenRootDir (DirHandle &dir) |
int | fileCloseDir (DirHandle dir) |
close a directory object More... | |
int | fileReadDir (DirHandle dir, FileStat &stat) |
Read a directory entry. More... | |
int | fileRewindDir (DirHandle dir) |
Rewind to start of directory entries. More... | |
int | fileGetSystemInfo (IFS::FileSystem::Info &info) |
Get basic file system information. More... | |
IFS::FileSystem::Type | fileSystemType () |
Get the type of file system currently mounted (if any) More... | |
int | fileSystemFormat () |
Format the active file system. More... | |
int | fileSystemCheck () |
Perform a consistency check/repair on the active file system. More... | |
int | fileSetACL (FileHandle file, const IFS::ACL &acl) |
Set access control information. More... | |
int | fileSetTime (FileHandle file, time_t mtime) |
Set access control information for file. More... | |
String | IFS::Error::toString (int err) |
get text for an error code More... | |
bool | IFS::Error::isSystem (int err) |
Determine if the given IFS error code is system-specific. More... | |
int | IFS::Error::fromSystem (int syscode) |
Translate system error code into IFS error code. More... | |
int | IFS::Error::toSystem (int err) |
Translate IFS error code into SYSTEM code. More... | |
String | toString (IFS::IFileSystem::Type type) |
Get String for filesystem type. More... | |
String | toString (IFS::IFileSystem::Attribute attr) |
Get String for a filesystem attribute. More... | |
Variables | |
constexpr int | FS_OK = IFS::FS_OK |
constexpr SeekOrigin | eSO_FileStart {SeekOrigin::Start} |
constexpr SeekOrigin | eSO_CurrentPos {SeekOrigin::Current} |
constexpr SeekOrigin | eSO_FileEnd {SeekOrigin::End} |
constexpr FileOpenFlags | eFO_ReadOnly {File::ReadOnly} |
constexpr FileOpenFlags | eFO_WriteOnly {File::WriteOnly} |
constexpr FileOpenFlags | eFO_ReadWrite {File::ReadWrite} |
constexpr FileOpenFlags | eFO_CreateIfNotExist {File::Create} |
constexpr FileOpenFlags | eFO_Append {File::Append} |
constexpr FileOpenFlags | eFO_Truncate {File::Truncate} |
constexpr FileOpenFlags | eFO_CreateNewAlways {File::CreateNewAlways} |
constexpr ErrorCode | IFS::Error::USER {-100} |
constexpr ErrorCode | IFS::Error::SYSTEM {-1000} |
constexpr ErrorCode | IFS::FS_OK = Error::Success |
Set file attributes | |||||||
| |||||||
int | fileSetAttr (const char *filename, FileAttributes attr) | ||||||
int | fileSetAttr (const String &filename, FileAttributes attr) | ||||||
Detailed Description
Access file system.
Installable file system.
Error.h IFS Error codes and related stuff
Created: August 2018
Copyright 2019 mikee47 mike@ sill yhous e.ne t
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/.
FileSystem.h
Created August 2018 by mikee471
Copyright 2019 mikee47 mike@ sill yhous e.ne t
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/.
IFileSystem.h Abstract interface definitions for filesystem implementators
Created: August 2018
Copyright 2019 mikee47 mike@ sill yhous e.ne t
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/.
Macro Definition Documentation
◆ CHECK_FS
#define CHECK_FS | ( | _method | ) |
◆ FILE_SYSTEM_ATTR_MAP
#define FILE_SYSTEM_ATTR_MAP | ( | XX | ) |
Attribute flags for filing system.
◆ FILESYSTEM_TYPE_MAP
#define FILESYSTEM_TYPE_MAP | ( | XX | ) |
Four-character tag to identify type of filing system.
- Note
- As new filing systems are incorporated into IFS, update this enumeration
◆ IFS_ERROR_MAP
#define IFS_ERROR_MAP | ( | XX | ) |
IFS return codes.
An IFS implementation must return negative values for errors. Wrappers may use these IFS codes instead of their own. If returning an internal error code it may need to be translated. Methods returning ONLY an error code (i.e. not FileHandle) may return positive 'error' codes for information purposes. See IFileSystem::check() as an example. Return value usage is consistent with SPIFFS.
These codes are allocated using an enum since they are purely for internal purposes.
◆ XX [1/2]
#define XX | ( | tag, | |
text | |||
) | tag, |
◆ XX [2/2]
Typedef Documentation
◆ DirHandle
using DirHandle = IFS::DirHandle |
◆ ErrorCode
using IFS::ErrorCode = typedef int |
◆ file_t
using file_t = IFS::FileHandle |
<
◆ FileAttribute
using FileAttribute = IFS::FileAttribute |
◆ FileAttributes
using FileAttributes = IFS::FileAttributes |
◆ FileHandle
using FileHandle = IFS::FileHandle |
◆ FileNameStat
using FileNameStat = IFS::NameStat |
◆ FileOpenFlag
using FileOpenFlag = IFS::OpenFlag |
◆ FileOpenFlags
using FileOpenFlags = IFS::OpenFlags |
◆ FileStat
◆ SeekOriginFlags
typedef SeekOrigin SeekOriginFlags |
- Deprecated:
- Use
SeekOrigin
instead
Enumeration Type Documentation
◆ Value
|
strong |
Function Documentation
◆ dirExist() [1/2]
|
inline |
Check if a directory exists on file system.
- Parameters
-
dirName Full path to directory to check for
- Return values
-
bool true if directory exists
◆ dirExist() [2/2]
◆ fileClose()
|
inline |
Clode file.
- Parameters
-
file Handle of file to close
- Note
- File Handle is returned from fileOpen function
◆ fileCloseDir()
close a directory object
- Parameters
-
dir directory to close
- Return values
-
int Error code
◆ fileDelete() [1/3]
|
inline |
Delete file.
- Parameters
-
name Name of file to delete
- Return values
-
int Error code
◆ fileDelete() [2/3]
◆ fileDelete() [3/3]
|
inline |
Delete file.
- Parameters
-
file handle of file to delete
- Return values
-
int Error code
◆ fileExist() [1/2]
|
inline |
Check if a file exists on file system.
- Parameters
-
fileName Full path to file to check for
- Return values
-
bool true if file exists
◆ fileExist() [2/2]
◆ fileFlush()
|
inline |
Flush pending writes.
- Parameters
-
file File handle
- Return values
-
int Size of last file written or error code
◆ fileFreeFileSystem()
|
inline |
◆ fileGetContent() [1/3]
String fileGetContent | ( | const TFileName & | fileName | ) |
Read content of a file.
- Parameters
-
fileName Name of file to read from
- Note
- After calling this function the content of the file is placed in to a string. The result will be an invalid String (equates to
false
) if the file could not be read. If the file exists, but is empty, the result will be an empty string "".
◆ fileGetContent() [2/3]
|
inline |
Read content of a file.
- Parameters
-
fileName Name of file to read from buffer Pointer to a character buffer in to which to read the file content bufSize Quantity of bytes to read from file
- Return values
-
size_t Quantity of bytes read from file or zero on failure
- Note
- After calling this function the content of the file is placed in to a c-string Ensure there is sufficient space in the buffer for file content plus extra trailing null, i.e. at least bufSize + 1 Always check the return value!
- Returns 0 if the file could not be read
◆ fileGetContent() [3/3]
|
inline |
◆ fileGetErrorString()
◆ fileGetSize()
|
inline |
Get size of file.
- Parameters
-
fileName Name of file
- Return values
-
uint32_t Size of file in bytes, 0 on error
◆ fileGetSystemInfo()
|
inline |
Get basic file system information.
- Return values
-
int Error code
◆ fileIsEOF()
|
inline |
◆ fileList()
Get list of files on file system.
- Return values
-
Vector<String> Vector of strings. Each string element contains the name of a file on the file system
- Deprecated:
- use
Directory
object (or fileOpenDir / fileReadDir / fileCloseDir)
◆ fileMountFileSystem()
bool fileMountFileSystem | ( | IFS::IFileSystem * | fs | ) |
Mount a constructed filesystem with debug messages.
◆ fileOpen()
|
inline |
Open file by path.
- Parameters
-
path Full path to file flags Mode to open file
- Return values
-
file File handle or negative error code
◆ fileOpenDir() [1/2]
Open a named directory for reading.
- Parameters
-
name Name of directory to open, empty or "/" for root dir Directory object
- Return values
-
int Error code
◆ fileOpenDir() [2/2]
◆ fileOpenRootDir()
◆ fileRead()
|
inline |
Read from file.
- Parameters
-
file File handle data Pointer to data buffer in to which to read data size Quantity of data elements to read from file
- Return values
-
int Quantity of data elements actually read from file or negative error code
◆ fileReadDir()
Read a directory entry.
- Parameters
-
dir The directory object returned by fileOpenDir() stat The returned information, owned by DirHandle object
- Return values
-
int Error code
◆ fileRename() [1/2]
|
inline |
Rename file.
- Parameters
-
oldName Original name of file to rename newName New name for file
- Return values
-
int Error code
◆ fileRename() [2/2]
◆ fileRewindDir()
Rewind to start of directory entries.
- Parameters
-
dir The directory object returned by fileOpenDir()
- Return values
-
int Error code
◆ fileSeek()
|
inline |
Position file cursor.
- Parameters
-
file File handle offset Quantity of bytes to move cursor origin Position from where to move cursor
- Return values
-
int Offset within file or negative error code
◆ fileSetACL()
|
inline |
◆ fileSetAttr() [1/2]
|
inline |
◆ fileSetAttr() [2/2]
|
inline |
◆ fileSetContent() [1/2]
|
inline |
Create or replace file with defined content.
- Parameters
-
fileName Name of file to create or replace content Pointer to c-string containing content to populate file with length Number of characters to write
- Return values
-
int Number of bytes transferred or error code
- Note
- This function creates a new file or replaces an existing file and populates the file with the content of a c-string buffer.
◆ fileSetContent() [2/2]
|
inline |
◆ fileSetFileSystem()
void fileSetFileSystem | ( | IFS::IFileSystem * | fileSystem | ) |
Sets the currently active file system.
- Parameters
-
fileSystem
- Note
- Any existing filing system is freed first. Typically the filing system implementation has helper functions which create and initialise the file system to a valid state. The last step is to call this function to make it active. Call this function with nullptr to inactivate the filing system.
◆ fileSetTime()
|
inline |
Set access control information for file.
- Parameters
-
file handle to open file, must have write access
- Return values
-
int Error code
- Note
- any writes to file will reset this to current time
◆ fileStats() [1/3]
Get file statistics.
- Parameters
-
name File name stat Pointer to SPIFFS statistic structure to populate
- Return values
-
int Error code
◆ fileStats() [2/3]
◆ fileStats() [3/3]
|
inline |
brief Get file statistics
- Parameters
-
file File handle stat Pointer to SPIFFS statistic structure to populate
- Return values
-
int Error code
◆ fileSystemCheck()
|
inline |
Perform a consistency check/repair on the active file system.
- Return values
-
int 0 if OK, < 0 unrecoverable errors, > 0 repairs required
◆ fileSystemFormat()
◆ fileSystemType()
IFS::FileSystem::Type fileSystemType | ( | ) |
Get the type of file system currently mounted (if any)
- Return values
-
FileSystemType the file system type
◆ fileTell()
|
inline |
Get position in file.
- Parameters
-
file File handle
- Return values
-
int32_t Read / write cursor position or error code
◆ fileTouch()
|
inline |
◆ fileTruncate() [1/3]
|
inline |
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
◆ fileTruncate() [2/3]
|
inline |
Truncate an open file at the current cursor position.
- Parameters
-
file Open file handle, must have Write access
- Return values
-
int Error code
◆ fileTruncate() [3/3]
int fileTruncate | ( | const TFileName & | fileName, |
size_t | newSize | ||
) |
Truncate (reduce) the size of a file.
- Parameters
-
fileName newSize
- Return values
-
int Error code
- Note
- In POSIX
truncate()
can also make the file bigger, however SPIFFS can only reduce the file size and will return an error if newSize > fileSize
◆ fileWrite()
|
inline |
Write to file.
- Parameters
-
file File handle data Pointer to data to write to file size Quantity of data elements to write to file
- Return values
-
int Quantity of data elements actually written to file or negative error code
◆ fromSystem()
◆ fwfs_mount() [1/2]
bool fwfs_mount | ( | ) |
Mount the first available FWFS volume.
- Return values
-
bool true on success
◆ fwfs_mount() [2/2]
bool fwfs_mount | ( | Storage::Partition | partition | ) |
Mount SPIFFS volume from a specific partition.
- Return values
-
bool true on success
◆ getFileSystem()
|
inline |
Get the currently active file system, if any.
- Return values
-
IFS::FileSystem*
◆ isSystem()
Determine if the given IFS error code is system-specific.
◆ toString() [1/3]
◆ toString() [2/3]
String toString | ( | IFS::IFileSystem::Type | type | ) |
Get String for filesystem type.
◆ toString() [3/3]
String toString | ( | IFS::IFileSystem::Attribute | attr | ) |
Get String for a filesystem attribute.
◆ toSystem()
Variable Documentation
◆ eFO_Append
constexpr FileOpenFlags eFO_Append {File::Append} |
◆ eFO_CreateIfNotExist
constexpr FileOpenFlags eFO_CreateIfNotExist {File::Create} |
◆ eFO_CreateNewAlways
constexpr FileOpenFlags eFO_CreateNewAlways {File::CreateNewAlways} |
◆ eFO_ReadOnly
constexpr FileOpenFlags eFO_ReadOnly {File::ReadOnly} |
◆ eFO_ReadWrite
constexpr FileOpenFlags eFO_ReadWrite {File::ReadWrite} |
◆ eFO_Truncate
constexpr FileOpenFlags eFO_Truncate {File::Truncate} |
◆ eFO_WriteOnly
constexpr FileOpenFlags eFO_WriteOnly {File::WriteOnly} |
◆ eSO_CurrentPos
constexpr SeekOrigin eSO_CurrentPos {SeekOrigin::Current} |
◆ eSO_FileEnd
constexpr SeekOrigin eSO_FileEnd {SeekOrigin::End} |
◆ eSO_FileStart
constexpr SeekOrigin eSO_FileStart {SeekOrigin::Start} |
◆ FS_OK [1/2]
constexpr int FS_OK = IFS::FS_OK |
◆ FS_OK [2/2]
constexpr ErrorCode IFS::FS_OK = Error::Success |
◆ SYSTEM
constexpr ErrorCode IFS::Error::SYSTEM {-1000} |
◆ USER
constexpr ErrorCode IFS::Error::USER {-100} |