SdFile Class Reference

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

#include <SdFat.h>

Inheritance diagram for SdFile:

[legend]

Collaboration diagram for SdFile:

[legend]

List of all members.

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, char *fileName, uint32_t size)
uint32_t	curCluster (void)
uint32_t	curPosition (void)
uint32_t	dirBlock (void)
uint8_t	dirEntry (dir_t &dir)
uint8_t	dirIndex (void)
uint32_t	fileSize (void)
uint32_t	firstCluster (void)
uint8_t	isDir (void)
uint8_t	isFile (void)
uint8_t	isOpen (void)
uint8_t	isSubDir (void)
uint8_t	isRoot (void)
void	ls (uint8_t flags=0, uint8_t indent=0)
uint8_t	makeDir (SdFile &dir, char *dirName)
uint8_t	open (SdFile &dirFile, uint16_t index, uint8_t oflag)
uint8_t	open (SdFile &dirFile, char *fileName, uint8_t oflag)
uint8_t	open (SdFile &dirFile, char *fileName)
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)
uint8_t	truncate (uint32_t size)
uint8_t	unbufferedRead (void)
SdVolume *	volume (void)
void	write (uint8_t b)
int16_t	write (const void *buf, uint16_t nbyte)
void	write (const char *str)
void	write_P (PGM_P str)
void	writeln_P (PGM_P str)
Static Public Member Functions
static void	dateTimeCallback (void(*dateTime)(uint16_t &date, uint16_t &time))
static void	dirName (dir_t &dir, char *name)
static void	printDirName (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, char *fileName)
Public Attributes
bool	writeError

Detailed Description

Access FAT16 and FAT32 files on SD and SDHC cards.

Constructor & Destructor Documentation

SdFile::SdFile ( void ) [inline]

Create an instance of SdFile.

Member Function Documentation

void SdFile::clearUnbufferedRead ( void ) [inline]

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]`	bgnBlock	the first block address for the file.
`[out]`	endBlock	the 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::createContiguous	(	SdFile &	dirFile,
		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]`	dirFile	The directory where the file will be created.
`[in]`	fileName	A valid DOS 8.3 file name.
`[in]`	size	The 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.

uint32_t SdFile::curCluster ( void ) [inline]

Returns:: The current cluster number for a file or directory.

uint32_t SdFile::curPosition ( void ) [inline]

Returns:: The current position for a file or directory.

static void SdFile::dateTimeCallback ( void(*)(uint16_t &date, uint16_t &time) dateTime ) [inline, static]

Set the date/time callback function

Parameters:

[in] dateTime The 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.

uint32_t SdFile::dirBlock ( void ) [inline]

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] dir Location 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::dirIndex ( void ) [inline]

Returns:: Index of this file's directory in the block dirBlock.

void SdFile::dirName	(	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]`	dir	The directory structure containing the name.
`[out]`	name	A 13 byte char array for the formatted name.

uint32_t SdFile::fileSize ( void ) [inline]

Returns:: The total number of bytes in a file or directory.

uint32_t SdFile::firstCluster ( void ) [inline]

Returns:: The first cluster number for a file or directory.

uint8_t SdFile::isDir ( void ) [inline]

Returns:: True if this is a SdFile for a directory else false.

uint8_t SdFile::isFile ( void ) [inline]

Returns:: True if this is a SdFile for a file else false.

uint8_t SdFile::isOpen ( void ) [inline]

Returns:: True if this is a SdFile for an open file/directory else false.

uint8_t SdFile::isRoot ( void ) [inline]

Returns:: True if this is a SdFile for the root directory.

uint8_t SdFile::isSubDir ( void ) [inline]

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] flags The inclusive OR of

LS_DATE - Print file modification date

LS_SIZE - Print file size.

LS_R - Recursive list of subdirectories.

Parameters:

[in] indent Amount of space before file name. Used for recursive list to indicate subdirectory level.

uint8_t SdFile::makeDir	(	SdFile &	dir,
		char *	dirName
	)

Make a new directory.

Parameters:

`[in]`	dir	An open SdFat instance for the directory that will containing the new directory.
`[in]`	dirName	A 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::open	(	SdFile &	dirFile,
		char *	fileName
	)			`[inline]`

For compatibility - do not use in new apps

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

Open a file or directory by name.

Parameters:

`[in]`	dirFile	An open SdFat instance for the directory containing the file to be opened.
`[in]`	fileName	A valid 8.3 DOS name for a file to be opened.
`[in]`	oflag	Values 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,
		uint16_t	index,
		uint8_t	oflag
	)

Open a file by index.

Parameters:

`[in]`	dirFile	An open SdFat instance for the directory.
`[in]`	index	The index of the directory entry for the file to be opened. The value for index is (directory file position)/32.
`[in]`	oflag	Values 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::openRoot ( SdVolume & vol )

Open a volume's root directory.

Parameters:

[in] vol The 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.

void SdFile::printDirName	(	dir_t &	dir,
		uint8_t	width
	)			`[static]`

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

Parameters:

`[in]`	dir	The directory structure containing the name.
`[in]`	width	Blank 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] fatDate The 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] fatTime The time field from a directory entry.

void SdFile::printTwoDigits ( uint8_t v ) [static]

Print a value as two digits to Serial.

Parameters:

[in] v Value to be printed, 0 <= v <= 99

int16_t SdFile::read	(	void *	buf,
		uint16_t	nbyte
	)

Read data from a file starting at the current position.

Parameters:

`[out]`	buf	Pointer to the location that will receive the data.
`[in]`	nbyte	Maximum 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.

int16_t SdFile::read ( void ) [inline]

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.

int8_t SdFile::readDir ( dir_t & dir )

Read the next directory entry from a directory file.

Parameters:

[out] dir The 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.

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.

uint8_t SdFile::remove	(	SdFile &	dirFile,
		char *	fileName
	)			`[static]`

Remove a file.

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

Parameters:

`[in]`	dirFile	The directory that contains the file.
`[in]`	fileName	The 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.

void SdFile::rewind ( void ) [inline]

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 ) [inline]

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

uint8_t SdFile::seekEnd ( void ) [inline]

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] pos The 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 ) [inline]

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] flags Values 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]`	year	Valid range 1980 - 2107 inclusive.
`[in]`	month	Valid range 1 - 12 inclusive.
`[in]`	day	Valid range 1 - 31 inclusive.
`[in]`	hour	Valid range 0 - 23 inclusive.
`[in]`	minute	Valid range 0 - 59 inclusive.
`[in]`	second	Valid 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] length The 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 ) [inline]

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 ) [inline]

Returns:: Unbuffered read flag.

SdVolume* SdFile::volume ( void ) [inline]

Returns:: SdVolume that contains this file.

void SdFile::write ( const char * str ) [virtual]

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

Use SdFile::writeError to check for errors.

Reimplemented from Print.

int16_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]`	buf	Pointer to the location of the data to be written.
`[in]`	nbyte	Number 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.

void 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.

Reimplemented from Print.

void SdFile::write_P ( PGM_P str )

Write a PROGMEM string to a file.

Use SdFile::writeError to check for errors.

void SdFile::writeln_P ( PGM_P str )

Write a PROGMEM string followed by CR/LF to a file.

Use SdFile::writeError to check for errors.

Member Data Documentation

bool SdFile::writeError

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().

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

Arduino/libraries/SdFat/SdFat.h
Arduino/libraries/SdFat/SdFat.cpp

Generated on Wed Dec 23 08:22:21 2009 for SdFat by 1.6.1

SdFile Class Reference

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation