Wraps up all file access methods. More...

#include <File.h>

Inheritance diagram for IFS::File:
Collaboration diagram for IFS::File:

Public Types

using ReadContentCallback = FileSystem::ReadContentCallback
 

Public Member Functions

 ~File ()
 
 operator bool () const
 
bool stat (Stat &stat)
 get file information More...
 
int control (ControlCode code, void *buffer, size_t bufSize)
 Low-level and non-standard file control operations. More...
 
template<typename T >
bool open (const T &path, OpenFlags flags=OpenFlag::Read)
 open a file by name/path More...
 
bool close ()
 close an open file More...
 
int read (void *data, size_t size)
 read content from a file and advance cursor More...
 
int write (const void *data, size_t size)
 write content to a file at current position and advance cursor More...
 
bool write (const String &s)
 
file_offset_t seek (file_offset_t offset, SeekOrigin origin)
 change file read/write position More...
 
bool eof ()
 determine if current file position is at end of file More...
 
file_offset_t tell ()
 get current file position More...
 
bool truncate (file_size_t new_size)
 Truncate (reduce) the size of an open file. More...
 
bool truncate ()
 Truncate an open file at the current cursor position. More...
 
bool flush ()
 flush any buffered data to physical media More...
 
bool setacl (const ACL &acl)
 Set access control information for file. More...
 
bool settime (time_t mtime)
 Set modification time for file. More...
 
bool setcompression (const Compression &compression)
 Set file compression information. More...
 
template<typename... ParamTypes>
bool setAttribute (AttributeTag tag, ParamTypes... params)
 
template<typename... ParamTypes>
int getAttribute (AttributeTag tag, ParamTypes... params)
 
template<typename... ParamTypes>
bool setUserAttribute (uint8_t tagValue, ParamTypes... params)
 
template<typename... ParamTypes>
int getUserAttribute (uint8_t tagValue, ParamTypes... params)
 
String getUserAttribute (uint8_t tagValue)
 
bool removeUserAttribute (uint8_t tagValue)
 
int enumAttributes (const AttributeEnumCallback &callback, void *buffer, size_t bufsize)
 
bool remove ()
 remove (delete) an open file (and close it) More...
 
file_size_t getSize ()
 Get size of file. More...
 
file_offset_t readContent (size_t size, const ReadContentCallback &callback)
 Read from current file position and invoke callback for each block read. More...
 
file_offset_t readContent (const ReadContentCallback &callback)
 Read from current file position to end of file and invoke callback for each block read. More...
 
String getContent ()
 Read content of the file, from current position. More...
 
FileHandle release ()
 Return current file handle and release ownership. More...
 
int getExtents (Storage::Partition *part, Extent *list, uint16_t extcount)
 
 FsBase (IFileSystem *filesys=nullptr)
 
- Public Member Functions inherited from IFS::FsBase
 FsBase (IFileSystem *filesys=nullptr)
 
bool isValid () const
 
int getLastError ()
 determine if an error occurred during operation More...
 
String getErrorString (int err) const
 
String getLastErrorString () const
 
FileSystemgetFileSystem () const
 

Static Public Attributes

Common flag combinations
static constexpr OpenFlags ReadOnly {OpenFlag::Read}
 Read-only. More...
 
static constexpr OpenFlags WriteOnly {OpenFlag::Write}
 Write-only. More...
 
static constexpr OpenFlags ReadWrite {OpenFlag::Read | OpenFlag::Write}
 Read + Write. More...
 
static constexpr OpenFlags Create {OpenFlag::Create}
 Create file if it doesn't exist. More...
 
static constexpr OpenFlags Append {OpenFlag::Append}
 Append to existing file. More...
 
static constexpr OpenFlags Truncate {OpenFlag::Truncate}
 Truncate existing file to zero length. More...
 
static constexpr OpenFlags CreateNewAlways
 Create new file or overwrite file if it exists. More...
 

Additional Inherited Members

- Protected Member Functions inherited from IFS::FsBase
bool check (int64_t res)
 Check file operation result and note error code. More...
 
- Protected Attributes inherited from IFS::FsBase
int lastError {FS_OK}
 

Detailed Description

Wraps up all file access methods.

Member Typedef Documentation

◆ ReadContentCallback

Constructor & Destructor Documentation

◆ ~File()

IFS::File::~File ( )
inline

Member Function Documentation

◆ close()

bool IFS::File::close ( )
inline

close an open file

Return values
booltrue on success

◆ control()

int IFS::File::control ( ControlCode  code,
void *  buffer,
size_t  bufSize 
)
inline

Low-level and non-standard file control operations.

Parameters
codeFCNTL_XXX code
bufferInput/Output buffer
bufSizeSize of buffer
Return values
interror 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.

◆ enumAttributes()

int IFS::File::enumAttributes ( const AttributeEnumCallback callback,
void *  buffer,
size_t  bufsize 
)
inline

◆ eof()

bool IFS::File::eof ( )
inline

determine if current file position is at end of file

Return values
booltrue if at EOF or file is invalid

◆ flush()

bool IFS::File::flush ( )
inline

flush any buffered data to physical media

Return values
booltrue on success

◆ FsBase()

IFS::FsBase::FsBase
inline

◆ getAttribute()

template<typename... ParamTypes>
int IFS::File::getAttribute ( AttributeTag  tag,
ParamTypes...  params 
)
inline

◆ getContent()

String IFS::File::getContent ( )
inline

Read content of the file, from current position.

Return values
StringString variable in to which to read the file content
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 "".

◆ getExtents()

int IFS::File::getExtents ( Storage::Partition part,
Extent list,
uint16_t  extcount 
)
inline

◆ getSize()

file_size_t IFS::File::getSize ( )
inline

Get size of file.

Return values
uint32_tSize of file in bytes, 0 on error

◆ getUserAttribute() [1/2]

String IFS::File::getUserAttribute ( uint8_t  tagValue)
inline

◆ getUserAttribute() [2/2]

template<typename... ParamTypes>
int IFS::File::getUserAttribute ( uint8_t  tagValue,
ParamTypes...  params 
)
inline

◆ open()

template<typename T >
bool IFS::File::open ( const T &  path,
OpenFlags  flags = OpenFlag::Read 
)
inline

open a file by name/path

Parameters
pathfull path to file
flagsopens for opening file
Return values
booltrue on success

◆ operator bool()

IFS::File::operator bool ( ) const
inlineexplicit

◆ read()

int IFS::File::read ( void *  data,
size_t  size 
)
inline

read content from a file and advance cursor

Parameters
databuffer to write into
sizesize of file buffer, maximum number of bytes to read
Return values
intnumber of bytes read or error code

◆ readContent() [1/2]

file_offset_t IFS::File::readContent ( const ReadContentCallback callback)
inline

Read from current file position to end of file and invoke callback for each block read.

Parameters
callback
Return values
file_offset_tNumber of bytes processed, or error code

◆ readContent() [2/2]

file_offset_t IFS::File::readContent ( size_t  size,
const ReadContentCallback callback 
)
inline

Read from current file position and invoke callback for each block read.

Parameters
sizeMaximum number of bytes to read
callback
Return values
intNumber of bytes processed, or error code

◆ release()

FileHandle IFS::File::release ( )
inline

Return current file handle and release ownership.

◆ remove()

bool IFS::File::remove ( )
inline

remove (delete) an open file (and close it)

Return values
booltrue on success

◆ removeUserAttribute()

bool IFS::File::removeUserAttribute ( uint8_t  tagValue)
inline

◆ seek()

file_offset_t IFS::File::seek ( file_offset_t  offset,
SeekOrigin  origin 
)
inline

change file read/write position

Parameters
offsetposition relative to origin
originwhere to seek from (start/end or current position)
Return values
intcurrent position or error code

◆ setacl()

bool IFS::File::setacl ( const ACL acl)
inline

Set access control information for file.

Parameters
acl
Return values
booltrue on success

◆ setAttribute()

template<typename... ParamTypes>
bool IFS::File::setAttribute ( AttributeTag  tag,
ParamTypes...  params 
)
inline

◆ setcompression()

bool IFS::File::setcompression ( const Compression compression)
inline

Set file compression information.

Parameters
compression
Return values
booltrue on success

◆ settime()

bool IFS::File::settime ( time_t  mtime)
inline

Set modification time for file.

Return values
booltrue on success
Note
any subsequent writes to file will reset this to current time

◆ setUserAttribute()

template<typename... ParamTypes>
bool IFS::File::setUserAttribute ( uint8_t  tagValue,
ParamTypes...  params 
)
inline

◆ stat()

bool IFS::File::stat ( Stat stat)
inline

get file information

Parameters
statstructure to return information in, may be null
Return values
booltrue on success

◆ tell()

file_offset_t IFS::File::tell ( )
inline

get current file position

Return values
int32_tcurrent position relative to start of file, or error code

◆ truncate() [1/2]

bool IFS::File::truncate ( )
inline

Truncate an open file at the current cursor position.

Return values
booltrue on success

◆ truncate() [2/2]

bool IFS::File::truncate ( file_size_t  new_size)
inline

Truncate (reduce) the size of an open file.

Parameters
newSize
Return values
booltrue on success

◆ write() [1/2]

bool IFS::File::write ( const String s)
inline

◆ write() [2/2]

int IFS::File::write ( const void *  data,
size_t  size 
)
inline

write content to a file at current position and advance cursor

Parameters
databuffer to read from
sizenumber of bytes to write
Return values
intnumber of bytes written or error code

Member Data Documentation

◆ Append

constexpr OpenFlags IFS::File::Append {OpenFlag::Append}
staticconstexpr

Append to existing file.

◆ Create

constexpr OpenFlags IFS::File::Create {OpenFlag::Create}
staticconstexpr

Create file if it doesn't exist.

◆ CreateNewAlways

constexpr OpenFlags IFS::File::CreateNewAlways
staticconstexpr
Initial value:
{OpenFlag::Create |
OpenFlag::Truncate}

Create new file or overwrite file if it exists.

◆ ReadOnly

constexpr OpenFlags IFS::File::ReadOnly {OpenFlag::Read}
staticconstexpr

Read-only.

◆ ReadWrite

constexpr OpenFlags IFS::File::ReadWrite {OpenFlag::Read | OpenFlag::Write}
staticconstexpr

Read + Write.

◆ Truncate

constexpr OpenFlags IFS::File::Truncate {OpenFlag::Truncate}
staticconstexpr

Truncate existing file to zero length.

◆ WriteOnly

constexpr OpenFlags IFS::File::WriteOnly {OpenFlag::Write}
staticconstexpr

Write-only.


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