ESP8266
Public Member Functions | Static Public Member Functions | Private Member Functions | Static Private Member Functions | Private Attributes | Static Private Attributes | List of all members
SdFile Class Reference

Access FAT16 and FAT32 files on SD and SDHC cards. More...

Inheritance diagram for SdFile:
Print

Public Member Functions

 SdFile (void)
 
void clearUnbufferedRead (void)
 
uint8_t close (void)
 
uint8_t contiguousRange (uint32_t *bgnBlock, uint32_t *endBlock)
 
uint8_t createContiguous (SdFile *dirFile, const char *fileName, uint32_t size)
 
uint32_t curCluster (void) const
 
uint32_t curPosition (void) const
 
uint32_t dirBlock (void) const
 
uint8_t dirEntry (dir_t *dir)
 
uint8_t dirIndex (void) const
 
uint32_t fileSize (void) const
 
uint32_t firstCluster (void) const
 
uint8_t isDir (void) const
 
uint8_t isFile (void) const
 
uint8_t isOpen (void) const
 
uint8_t isSubDir (void) const
 
uint8_t isRoot (void) const
 
void ls (uint8_t flags=0, uint8_t indent=0)
 
uint8_t makeDir (SdFile *dir, const char *dirName)
 
uint8_t open (SdFile *dirFile, uint16_t index, uint8_t oflag)
 
uint8_t open (SdFile *dirFile, const char *fileName, uint8_t oflag)
 
uint8_t openRoot (SdVolume *vol)
 
int16_t read (void)
 
int16_t read (void *buf, uint16_t nbyte)
 
int8_t readDir (dir_t *dir)
 
uint8_t remove (void)
 
void rewind (void)
 
uint8_t rmDir (void)
 
uint8_t rmRfStar (void)
 
uint8_t seekCur (uint32_t pos)
 
uint8_t seekEnd (void)
 
uint8_t seekSet (uint32_t pos)
 
void setUnbufferedRead (void)
 
uint8_t timestamp (uint8_t flag, uint16_t year, uint8_t month, uint8_t day, uint8_t hour, uint8_t minute, uint8_t second)
 
uint8_t sync (void)
 
uint8_t type (void) const
 
uint8_t truncate (uint32_t size)
 
uint8_t unbufferedRead (void) const
 
SdVolumevolume (void) const
 
size_t write (uint8_t b)
 
size_t write (const void *buf, uint16_t nbyte)
 
size_t write (const char *str)
 
uint8_t contiguousRange (uint32_t &bgnBlock, uint32_t &endBlock)
 
uint8_t createContiguous (SdFile &dirFile, const char *fileName, uint32_t size)
 
uint8_t dirEntry (dir_t &dir)
 
uint8_t makeDir (SdFile &dir, const char *dirName)
 
uint8_t open (SdFile &dirFile, const char *fileName, uint8_t oflag)
 
uint8_t open (SdFile &dirFile, const char *fileName)
 
uint8_t open (SdFile &dirFile, uint16_t index, uint8_t oflag)
 
uint8_t openRoot (SdVolume &vol)
 
int8_t readDir (dir_t &dir)
 
- Public Member Functions inherited from Print
 Print ()
 
int getWriteError ()
 
void clearWriteError ()
 
size_t write (const char *str)
 
virtual size_t write (const uint8_t *buffer, size_t size)
 
size_t write (const char *buffer, size_t size)
 
size_t printf (const char *format,...) __attribute__((format(printf
 
size_t size_t print (const __FlashStringHelper *)
 
size_t print (const String &)
 
size_t print (const char[])
 
size_t print (char)
 
size_t print (unsigned char, int=10)
 
size_t print (int, int=10)
 
size_t print (unsigned int, int=10)
 
size_t print (long, int=10)
 
size_t print (unsigned long, int=10)
 
size_t print (double, int=2)
 
size_t print (const Printable &)
 
size_t println (const __FlashStringHelper *)
 
size_t println (const String &s)
 
size_t println (const char[])
 
size_t println (char)
 
size_t println (unsigned char, int=10)
 
size_t println (int, int=10)
 
size_t println (unsigned int, int=10)
 
size_t println (long, int=10)
 
size_t println (unsigned long, int=10)
 
size_t println (double, int=2)
 
size_t println (const Printable &)
 
size_t println (void)
 

Static Public Member Functions

static void dateTimeCallback (void(*dateTime)(uint16_t *date, uint16_t *time))
 
static void dateTimeCallbackCancel (void)
 
static void dirName (const dir_t &dir, char *name)
 
static void printDirName (const dir_t &dir, uint8_t width)
 
static void printFatDate (uint16_t fatDate)
 
static void printFatTime (uint16_t fatTime)
 
static void printTwoDigits (uint8_t v)
 
static uint8_t remove (SdFile *dirFile, const char *fileName)
 
static void dateTimeCallback (void(*dateTime)(uint16_t &date, uint16_t &time))
 
static uint8_t remove (SdFile &dirFile, const char *fileName)
 

Private Member Functions

uint8_t addCluster (void)
 
uint8_t addDirCluster (void)
 
dir_tcacheDirEntry (uint8_t action)
 
uint8_t openCachedEntry (uint8_t cacheIndex, uint8_t oflags)
 
dir_treadDirCache (void)
 

Static Private Member Functions

static void oldToNew (uint16_t *date, uint16_t *time)
 
static uint8_t make83Name (const char *str, uint8_t *name)
 

Private Attributes

uint8_t flags_
 
uint8_t type_
 
uint32_t curCluster_
 
uint32_t curPosition_
 
uint32_t dirBlock_
 
uint8_t dirIndex_
 
uint32_t fileSize_
 
uint32_t firstCluster_
 
SdVolumevol_
 

Static Private Attributes

static void(* oldDateTime_ )(uint16_t &date, uint16_t &time) = NULL
 
static uint8_t const F_OFLAG = (O_ACCMODE | O_APPEND | O_SYNC)
 
static uint8_t const F_UNUSED = 0X30
 
static uint8_t const F_FILE_UNBUFFERED_READ = 0X40
 
static uint8_t const F_FILE_DIR_DIRTY = 0X80
 
static void(* dateTime_ )(uint16_t *date, uint16_t *time) = NULL
 

Additional Inherited Members

- Protected Member Functions inherited from Print
void setWriteError (int err=1)
 

Detailed Description

Access FAT16 and FAT32 files on SD and SDHC cards.

Constructor & Destructor Documentation

SdFile::SdFile ( void  )

Create an instance of SdFile.

Member Function Documentation

uint8_t SdFile::addCluster ( void  )
private
uint8_t SdFile::addDirCluster ( void  )
private
dir_t * SdFile::cacheDirEntry ( uint8_t  action)
private
void SdFile::clearUnbufferedRead ( void  )

writeError is set to true if an error occurs during a write(). Set writeError to false before calling print() and/or write() and check for true after calls to print() and/or write(). Cancel unbuffered reads for this file. See setUnbufferedRead()

uint8_t SdFile::close ( void  )

Close a file and force cached data and directory information to be written to the storage device.

Returns
The value one, true, is returned for success and the value zero, false, is returned for failure. Reasons for failure include no file is open or an I/O error.
uint8_t SdFile::contiguousRange ( uint32_t *  bgnBlock,
uint32_t *  endBlock 
)

Check for contiguous file and return its raw block range.

Parameters
[out]bgnBlockthe first block address for the file.
[out]endBlockthe last block address for the file.
Returns
The value one, true, is returned for success and the value zero, false, is returned for failure. Reasons for failure include file is not contiguous, file has zero length or an I/O error occurred.
uint8_t SdFile::contiguousRange ( uint32_t &  bgnBlock,
uint32_t &  endBlock 
)
uint8_t SdFile::createContiguous ( SdFile dirFile,
const char *  fileName,
uint32_t  size 
)

Create and open a new contiguous file of a specified size.

Note
This function only supports short DOS 8.3 names. See open() for more information.
Parameters
[in]dirFileThe directory where the file will be created.
[in]fileNameA valid DOS 8.3 file name.
[in]sizeThe desired file size.
Returns
The value one, true, is returned for success and the value zero, false, is returned for failure. Reasons for failure include fileName contains an invalid DOS 8.3 file name, the FAT volume has not been initialized, a file is already open, the file already exists, the root directory is full or an I/O error.
uint8_t SdFile::createContiguous ( SdFile dirFile,
const char *  fileName,
uint32_t  size 
)
Deprecated:
Use: uint8_t SdFile::createContiguous(SdFile* dirFile, const char* fileName, uint32_t size)
uint32_t SdFile::curCluster ( void  ) const
Returns
The current cluster number for a file or directory.
uint32_t SdFile::curPosition ( void  ) const
Returns
The current position for a file or directory.
static void SdFile::dateTimeCallback ( void(*)(uint16_t *date, uint16_t *time)  dateTime)
static

Set the date/time callback function

Parameters
[in]dateTimeThe user's call back function. The callback function is of the form:
void dateTime(uint16_t* date, uint16_t* time) {
uint16_t year;
uint8_t month, day, hour, minute, second;
// User gets date and time from GPS or real-time clock here
// return date using FAT_DATE macro to format fields
*date = FAT_DATE(year, month, day);
// return time using FAT_TIME macro to format fields
*time = FAT_TIME(hour, minute, second);
}

Sets the function that is called when a file is created or when a file's directory entry is modified by sync(). All timestamps, access, creation, and modify, are set when a file is created. sync() maintains the last access date and last modify date/time.

See the timestamp() function.

static void SdFile::dateTimeCallback ( void(*)(uint16_t &date, uint16_t &time)  dateTime)
static
Deprecated:
Use: static void SdFile::dateTimeCallback( void (dateTime)(uint16_t date, uint16_t* time));
static void SdFile::dateTimeCallbackCancel ( void  )
static

Cancel the date/time callback function.

uint32_t SdFile::dirBlock ( void  ) const
Returns
Address of the block that contains this file's directory.
uint8_t SdFile::dirEntry ( dir_t dir)

Return a files directory entry

Parameters
[out]dirLocation for return of the files directory entry.
Returns
The value one, true, is returned for success and the value zero, false, is returned for failure.
uint8_t SdFile::dirEntry ( dir_t dir)
uint8_t SdFile::dirIndex ( void  ) const
Returns
Index of this file's directory in the block dirBlock.
void SdFile::dirName ( const dir_t dir,
char *  name 
)
static

Format the name field of dir into the 13 byte array name in standard 8.3 short name format.

Parameters
[in]dirThe directory structure containing the name.
[out]nameA 13 byte char array for the formatted name.
uint32_t SdFile::fileSize ( void  ) const
Returns
The total number of bytes in a file or directory.
uint32_t SdFile::firstCluster ( void  ) const
Returns
The first cluster number for a file or directory.
uint8_t SdFile::isDir ( void  ) const
Returns
True if this is a SdFile for a directory else false.
uint8_t SdFile::isFile ( void  ) const
Returns
True if this is a SdFile for a file else false.
uint8_t SdFile::isOpen ( void  ) const
Returns
True if this is a SdFile for an open file/directory else false.
uint8_t SdFile::isRoot ( void  ) const
Returns
True if this is a SdFile for the root directory.
uint8_t SdFile::isSubDir ( void  ) const
Returns
True if this is a SdFile for a subdirectory else false.
void SdFile::ls ( uint8_t  flags = 0,
uint8_t  indent = 0 
)

List directory contents to Serial.

Parameters
[in]flagsThe inclusive OR of

LS_DATE - Print file modification date

LS_SIZE - Print file size.

LS_R - Recursive list of subdirectories.

Parameters
[in]indentAmount of space before file name. Used for recursive list to indicate subdirectory level.
uint8_t SdFile::make83Name ( const char *  str,
uint8_t *  name 
)
staticprivate
uint8_t SdFile::makeDir ( SdFile dir,
const char *  dirName 
)

Make a new directory.

Parameters
[in]dirAn open SdFat instance for the directory that will containing the new directory.
[in]dirNameA valid 8.3 DOS name for the new directory.
Returns
The value one, true, is returned for success and the value zero, false, is returned for failure. Reasons for failure include this SdFile is already open, dir is not a directory, dirName is invalid or already exists in dir.
uint8_t SdFile::makeDir ( SdFile dir,
const char *  dirName 
)
static void SdFile::oldToNew ( uint16_t *  date,
uint16_t *  time 
)
staticprivate
uint8_t SdFile::open ( SdFile dirFile,
uint16_t  index,
uint8_t  oflag 
)

Open a file by index.

Parameters
[in]dirFileAn open SdFat instance for the directory.
[in]indexThe index of the directory entry for the file to be opened. The value for index is (directory file position)/32.
[in]oflagValues for oflag are constructed by a bitwise-inclusive OR of flags O_READ, O_WRITE, O_TRUNC, and O_SYNC.

See open() by fileName for definition of flags and return values.

uint8_t SdFile::open ( SdFile dirFile,
const char *  fileName,
uint8_t  oflag 
)

Open a file or directory by name.

Parameters
[in]dirFileAn open SdFat instance for the directory containing the file to be opened.
[in]fileNameA valid 8.3 DOS name for a file to be opened.
[in]oflagValues for oflag are constructed by a bitwise-inclusive OR of flags from the following list

O_READ - Open for reading.

O_RDONLY - Same as O_READ.

O_WRITE - Open for writing.

O_WRONLY - Same as O_WRITE.

O_RDWR - Open for reading and writing.

O_APPEND - If set, the file offset shall be set to the end of the file prior to each write.

O_CREAT - If the file exists, this flag has no effect except as noted under O_EXCL below. Otherwise, the file shall be created

O_EXCL - If O_CREAT and O_EXCL are set, open() shall fail if the file exists.

O_SYNC - Call sync() after each write. This flag should not be used with write(uint8_t), write_P(PGM_P), writeln_P(PGM_P), or the Arduino Print class. These functions do character at a time writes so sync() will be called after each byte.

O_TRUNC - If the file exists and is a regular file, and the file is successfully opened and is not read only, its length shall be truncated to 0.

Note
Directory files must be opened read only. Write and truncation is not allowed for directory files.
Returns
The value one, true, is returned for success and the value zero, false, is returned for failure. Reasons for failure include this SdFile is already open, difFile is not a directory, fileName is invalid, the file does not exist or can't be opened in the access mode specified by oflag.
uint8_t SdFile::open ( SdFile dirFile,
const char *  fileName,
uint8_t  oflag 
)
uint8_t SdFile::open ( SdFile dirFile,
const char *  fileName 
)
Deprecated:
Do not use in new apps
uint8_t SdFile::open ( SdFile dirFile,
uint16_t  index,
uint8_t  oflag 
)
uint8_t SdFile::openCachedEntry ( uint8_t  cacheIndex,
uint8_t  oflags 
)
private
uint8_t SdFile::openRoot ( SdVolume vol)

Open a volume's root directory.

Parameters
[in]volThe FAT volume containing the root directory to be opened.
Returns
The value one, true, is returned for success and the value zero, false, is returned for failure. Reasons for failure include the FAT volume has not been initialized or it a FAT12 volume.
uint8_t SdFile::openRoot ( SdVolume vol)
void SdFile::printDirName ( const dir_t dir,
uint8_t  width 
)
static

Print the name field of a directory entry in 8.3 format to Serial.

Parameters
[in]dirThe directory structure containing the name.
[in]widthBlank fill name if length is less than width.
void SdFile::printFatDate ( uint16_t  fatDate)
static

Print a directory date field to Serial.

Format is yyyy-mm-dd.

Parameters
[in]fatDateThe date field from a directory entry.
void SdFile::printFatTime ( uint16_t  fatTime)
static

Print a directory time field to Serial.

Format is hh:mm:ss.

Parameters
[in]fatTimeThe time field from a directory entry.
void SdFile::printTwoDigits ( uint8_t  v)
static

Print a value as two digits to Serial.

Parameters
[in]vValue to be printed, 0 <= v <= 99
int16_t SdFile::read ( void  )

Read the next byte from a file.

Returns
For success read returns the next byte in the file as an int. If an error occurs or end of file is reached -1 is returned.
int16_t SdFile::read ( void *  buf,
uint16_t  nbyte 
)

Read data from a file starting at the current position.

Parameters
[out]bufPointer to the location that will receive the data.
[in]nbyteMaximum number of bytes to read.
Returns
For success read() returns the number of bytes read. A value less than nbyte, including zero, will be returned if end of file is reached. If an error occurs, read() returns -1. Possible errors include read() called before a file has been opened, corrupt file system or an I/O error occurred.
int8_t SdFile::readDir ( dir_t dir)

Read the next directory entry from a directory file.

Parameters
[out]dirThe dir_t struct that will receive the data.
Returns
For success readDir() returns the number of bytes read. A value of zero will be returned if end of file is reached. If an error occurs, readDir() returns -1. Possible errors include readDir() called before a directory has been opened, this is not a directory file or an I/O error occurred.
int8_t SdFile::readDir ( dir_t dir)
dir_t * SdFile::readDirCache ( void  )
private
uint8_t SdFile::remove ( SdFile dirFile,
const char *  fileName 
)
static

Remove a file.

The directory entry and all data for the file are deleted.

Parameters
[in]dirFileThe directory that contains the file.
[in]fileNameThe name of the file to be removed.
Note
This function should not be used to delete the 8.3 version of a file that has a long name. For example if a file has the long name "New Text Document.txt" you should not delete the 8.3 name "NEWTEX~1.TXT".
Returns
The value one, true, is returned for success and the value zero, false, is returned for failure. Reasons for failure include the file is a directory, is read only, dirFile is not a directory, fileName is not found or an I/O error occurred.
uint8_t SdFile::remove ( void  )

Remove a file.

The directory entry and all data for the file are deleted.

Note
This function should not be used to delete the 8.3 version of a file that has a long name. For example if a file has the long name "New Text Document.txt" you should not delete the 8.3 name "NEWTEX~1.TXT".
Returns
The value one, true, is returned for success and the value zero, false, is returned for failure. Reasons for failure include the file read-only, is a directory, or an I/O error occurred.
static uint8_t SdFile::remove ( SdFile dirFile,
const char *  fileName 
)
static
void SdFile::rewind ( void  )

Set the file's current position to zero.

uint8_t SdFile::rmDir ( void  )

Remove a directory file.

The directory file will be removed only if it is empty and is not the root directory. rmDir() follows DOS and Windows and ignores the read-only attribute for the directory.

Note
This function should not be used to delete the 8.3 version of a directory that has a long name. For example if a directory has the long name "New folder" you should not delete the 8.3 name "NEWFOL~1".
Returns
The value one, true, is returned for success and the value zero, false, is returned for failure. Reasons for failure include the file is not a directory, is the root directory, is not empty, or an I/O error occurred.
uint8_t SdFile::rmRfStar ( void  )

Recursively delete a directory and all contained files.

This is like the Unix/Linux 'rm -rf *' if called with the root directory hence the name.

Warning - This will remove all contents of the directory including subdirectories. The directory will then be removed if it is not root. The read-only attribute for files will be ignored.

Note
This function should not be used to delete the 8.3 version of a directory that has a long name. See remove() and rmDir().
Returns
The value one, true, is returned for success and the value zero, false, is returned for failure.
uint8_t SdFile::seekCur ( uint32_t  pos)

Set the files position to current position + pos. See seekSet().

uint8_t SdFile::seekEnd ( void  )

Set the files current position to end of file. Useful to position a file for append. See seekSet().

uint8_t SdFile::seekSet ( uint32_t  pos)

Sets a file's position.

Parameters
[in]posThe new position in bytes from the beginning of the file.
Returns
The value one, true, is returned for success and the value zero, false, is returned for failure.
void SdFile::setUnbufferedRead ( void  )

Use unbuffered reads to access this file. Used with Wave Shield ISR. Used with Sd2Card::partialBlockRead() in WaveRP.

Not recommended for normal applications.

uint8_t SdFile::sync ( void  )

The sync() call causes all modified data and directory fields to be written to the storage device.

Returns
The value one, true, is returned for success and the value zero, false, is returned for failure. Reasons for failure include a call to sync() before a file has been opened or an I/O error.
uint8_t SdFile::timestamp ( uint8_t  flags,
uint16_t  year,
uint8_t  month,
uint8_t  day,
uint8_t  hour,
uint8_t  minute,
uint8_t  second 
)

Set a file's timestamps in its directory entry.

Parameters
[in]flagsValues for flags are constructed by a bitwise-inclusive OR of flags from the following list

T_ACCESS - Set the file's last access date.

T_CREATE - Set the file's creation date and time.

T_WRITE - Set the file's last write/modification date and time.

Parameters
[in]yearValid range 1980 - 2107 inclusive.
[in]monthValid range 1 - 12 inclusive.
[in]dayValid range 1 - 31 inclusive.
[in]hourValid range 0 - 23 inclusive.
[in]minuteValid range 0 - 59 inclusive.
[in]secondValid range 0 - 59 inclusive
Note
It is possible to set an invalid date since there is no check for the number of days in a month.
Modify and access timestamps may be overwritten if a date time callback function has been set by dateTimeCallback().
Returns
The value one, true, is returned for success and the value zero, false, is returned for failure.
uint8_t SdFile::truncate ( uint32_t  length)

Truncate a file to a specified length. The current file position will be maintained if it is less than or equal to length otherwise it will be set to end of file.

Parameters
[in]lengthThe desired length for the file.
Returns
The value one, true, is returned for success and the value zero, false, is returned for failure. Reasons for failure include file is read only, file is a directory, length is greater than the current file size or an I/O error occurs.
uint8_t SdFile::type ( void  ) const

Type of this SdFile. You should use isFile() or isDir() instead of type() if possible.

Returns
The file or directory type.
uint8_t SdFile::unbufferedRead ( void  ) const
Returns
Unbuffered read flag.
SdVolume* SdFile::volume ( void  ) const
Returns
SdVolume that contains this file.
size_t SdFile::write ( uint8_t  b)
virtual

Write a byte to a file. Required by the Arduino Print class.

Use SdFile::writeError to check for errors.

Implements Print.

size_t SdFile::write ( const void *  buf,
uint16_t  nbyte 
)

Write data to an open file.

Note
Data is moved to the cache but may not be written to the storage device until sync() is called.
Parameters
[in]bufPointer to the location of the data to be written.
[in]nbyteNumber of bytes to write.
Returns
For success write() returns the number of bytes written, always nbyte. If an error occurs, write() returns -1. Possible errors include write() is called before a file has been opened, write is called for a read-only file, device is full, a corrupt file system or an I/O error.
size_t SdFile::write ( const char *  str)

Write a string to a file. Used by the Arduino Print class.

Use SdFile::writeError to check for errors.

Member Data Documentation

uint32_t SdFile::curCluster_
private
uint32_t SdFile::curPosition_
private
void(* SdFile::dateTime_)(uint16_t *date, uint16_t *time) = NULL
staticprivate
uint32_t SdFile::dirBlock_
private
uint8_t SdFile::dirIndex_
private
uint8_t const SdFile::F_FILE_DIR_DIRTY = 0X80
staticprivate
uint8_t const SdFile::F_FILE_UNBUFFERED_READ = 0X40
staticprivate
uint8_t const SdFile::F_OFLAG = (O_ACCMODE | O_APPEND | O_SYNC)
staticprivate
uint8_t const SdFile::F_UNUSED = 0X30
staticprivate
uint32_t SdFile::fileSize_
private
uint32_t SdFile::firstCluster_
private
uint8_t SdFile::flags_
private
void(* SdFile::oldDateTime_)(uint16_t &date, uint16_t &time) = NULL
staticprivate
uint8_t SdFile::type_
private
SdVolume* SdFile::vol_
private