Sming Framework API
Sming - Open Source framework for high efficiency WiFi SoC ESP8266 native development with C++ language.
File system

Access file system. More...

Enumerations

enum  FileOpenFlags {
  eFO_ReadOnly = SPIFFS_RDONLY,
  eFO_WriteOnly = SPIFFS_WRONLY,
  eFO_ReadWrite = eFO_ReadOnly | eFO_WriteOnly,
  eFO_CreateIfNotExist = SPIFFS_CREAT,
  eFO_Append = SPIFFS_APPEND,
  eFO_Truncate = SPIFFS_TRUNC,
  eFO_CreateNewAlways = eFO_CreateIfNotExist | eFO_Truncate
}
 File open flags. More...
 
enum  SeekOriginFlags {
  eSO_FileStart = SPIFFS_SEEK_SET,
  eSO_CurrentPos = SPIFFS_SEEK_CUR,
  eSO_FileEnd = SPIFFS_SEEK_END
}
 File seek flags. More...
 

Functions

static FileOpenFlags operator| (FileOpenFlags lhs, FileOpenFlags rhs)
 
file_t fileOpen (const String &name, FileOpenFlags flags)
 Open file. More...
 
void fileClose (file_t file)
 Clode file. More...
 
size_t fileWrite (file_t file, const void *data, size_t size)
 Write to file. More...
 
size_t fileRead (file_t file, void *data, size_t size)
 Read from file. More...
 
int fileSeek (file_t file, int offset, SeekOriginFlags origin)
 Position file cursor. More...
 
bool fileIsEOF (file_t file)
 Check if at end of file. More...
 
int32_t fileTell (file_t file)
 Get position in file. More...
 
int fileFlush (file_t file)
 Flush pending writes. More...
 
int fileLastError (file_t fd)
 Get last file system error code. More...
 
void fileClearLastError (file_t fd)
 Clear last file system error. More...
 
int fileSetContent (const String &fileName, const char *content)
 Create or replace file with defined content. More...
 
int fileSetContent (const String &fileName, const String &content)
 Create or replace file with defined content. More...
 
uint32_t fileGetSize (const String &fileName)
 Get size of file. More...
 
void fileRename (const String &oldName, const String &newName)
 Rename file. More...
 
Vector< StringfileList ()
 Get list of files on file system. More...
 
String fileGetContent (const String &fileName)
 Read content of a file. More...
 
int fileGetContent (const String &fileName, char *buffer, int bufSize)
 Read content of a file. More...
 
int fileStats (const String &name, spiffs_stat *stat)
 
int fileStats (file_t file, spiffs_stat *stat)
 
int fileDelete (const String &name)
 Delete file. More...
 
int fileDelete (file_t file)
 Delete file. More...
 
bool fileExist (const String &name)
 Check if a file exists on file system. More...
 

Detailed Description

Access file system.

Enumeration Type Documentation

File open flags.

Enumerator
eFO_ReadOnly 

Read only file.

eFO_WriteOnly 

Write only file.

eFO_ReadWrite 

Read and write file.

eFO_CreateIfNotExist 

Create new file if file does not exist.

eFO_Append 

Append to file.

eFO_Truncate 

Truncate file.

eFO_CreateNewAlways 

Create new file even if file exists.

File seek flags.

Enumerator
eSO_FileStart 

Start of file.

eSO_CurrentPos 

Current position in file.

eSO_FileEnd 

End of file.

Function Documentation

void fileClearLastError ( file_t  fd)

Clear last file system error.

Parameters
fdNot used
Todo:
Why does fileClearLastError have unused fd parameter?
void fileClose ( file_t  file)

Clode file.

Parameters
fileID of file to open
Note
File ID is returned from fileOpen function
int fileDelete ( const String name)

Delete file.

Parameters
nameName of file to delete
Return values
interror code, 0 on success
int fileDelete ( file_t  file)

Delete file.

Parameters
fileID of file to delete
Return values
interror code, 0 on success
bool fileExist ( const String name)

Check if a file exists on file system.

Parameters
nameName of file to check for
Return values
boolTrue if file exists
int fileFlush ( file_t  file)

Flush pending writes.

Parameters
fileFile ID
Return values
intSize of last file written or negative error number
String fileGetContent ( const String fileName)

Read content of a file.

Parameters
fileNameName of file to read from
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
int fileGetContent ( const String fileName,
char *  buffer,
int  bufSize 
)

Read content of a file.

Parameters
fileNameName of file to read from
bufferPointer to a character buffer in to which to read the file content
bufSizeQuantity of bytes to read from file
Return values
intQuantity 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
uint32_t fileGetSize ( const String fileName)

Get size of file.

Parameters
fileNameName of file
Return values
uint32_tSize of file in bytes
bool fileIsEOF ( file_t  file)

Check if at end of file.

Parameters
fileFile ID
Return values
boolTrue if at end of file
int fileLastError ( file_t  fd)

Get last file system error code.

Parameters
fdNot used
Todo:
Why does fileLastError have unused fd parameter?
Return values
intError code of last file system operation
Vector<String> 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
file_t fileOpen ( const String name,
FileOpenFlags  flags 
)

Open file.

Parameters
nameFile name
flagsMode to open file
Return values
fileFile ID or negative error code
size_t fileRead ( file_t  file,
void *  data,
size_t  size 
)

Read from file.

Parameters
fileFile ID
dataPointer to data buffer in to which to read data
sizeQuantity of data elements to read from file
Return values
size_tQuantity of data elements actually read from file or negative error code
void fileRename ( const String oldName,
const String newName 
)

Rename file.

Parameters
oldNameOriginal name of file to rename
newNameNew name for file
int fileSeek ( file_t  file,
int  offset,
SeekOriginFlags  origin 
)

Position file cursor.

Parameters
fileFile ID
offsetQuantity of bytes to move cursor
originPosition from where to move cursor
Return values
Offsetwithin file or negative error code
int fileSetContent ( const String fileName,
const char *  content 
)

Create or replace file with defined content.

Parameters
fileNameName of file to create or replace
contentPointer to c-string containing content to populate file with
Return values
intPositive integer represents the numbers of bytes written.
intNegative integer represents the error code of last file system operation.
Note
This function creates a new file or replaces an existing file and populates the file with the content of a c-string buffer. Remember to terminate your c-string buffer with a null (0).
int fileSetContent ( const String fileName,
const String content 
)

Create or replace file with defined content.

Parameters
fileNameName of file to create or replace
contentString containing content to populate file with
Return values
intPositive integer represents the numbers of bytes written.
intNegative integer represents the error code of last file system operation.
Note
This function creates a new file or replaces an existing file and populates the file with the content of a string.
int fileStats ( const String name,
spiffs_stat *  stat 
)

brief Get file statistics

Parameters
nameFile name
statPointer to SPIFFS statistic structure to populate
Return values
int-1 on error
Note
Pass a pointer to an instantiated fileStats structure
Todo:
Document the return value of fileStats
int fileStats ( file_t  file,
spiffs_stat *  stat 
)

brief Get file statistics

Parameters
fileFile ID
statPointer to SPIFFS statistic structure to populate
Return values
int-1 on error
Note
Pass a pointer to an instantiated fileStats structure
Todo:
Document the return value of fileStats
int32_t fileTell ( file_t  file)

Get position in file.

Parameters
fileFile ID
Return values
int32_tRead / write cursor position
size_t fileWrite ( file_t  file,
const void *  data,
size_t  size 
)

Write to file.

Parameters
fileFile ID
dataPointer to data to write to file
sizeQuantity of data elements to write to file
Return values
size_tQuantity of data elements actually written to file or negative error code