PropWare  3.0.0.224 C++ objects and CMake build system for Parallax Propeller

Read a file on a FAT 16 or FAT 32 storage device. More...

#include <PropWare/filesystem/fat/fatfilereader.h>

## Public Types

enum  ErrorCode {
NO_ERROR = 0,
BEG_ERROR = Filesystem::END_ERROR + 1,
ENTRY_NOT_FILE = BEG_ERROR,
FILENAME_NOT_FOUND,
END_ERROR = FILENAME_NOT_FOUND
}

enum  SeekDir {
SeekDir::BEG,
SeekDir::CUR,
SeekDir::END
}

## Public Member Functions

FatFileReader (FatFS &fs, const char name[], BlockStorage::Buffer &buffer=SHARED_BUFFER, const Printer &logger=pwOut)
Construct a new file instance. More...

PropWare::ErrorCode open ()
Open the file. More...

PropWare::ErrorCode safe_get_char (char &c)
Read a character from the file. More...

const char * get_name () const
Determine the name of a file. More...

bool exists () const
Determine if a file exists (file does not have to be open) More...

bool exists (PropWare::ErrorCode &err) const

virtual PropWare::ErrorCode close ()
Close a file - a required step in any workflow that includes opening a file. More...

virtual PropWare::ErrorCode flush ()=0
Flush any modified data back to the SD card. More...

int32_t get_length () const
Return the number of bytes (characters) in the file.

int32_t tell () const
Obtain the value of the file position indicator. More...

PropWare::ErrorCode seek (const int32_t offset, const SeekDir way)
Sets the position of the next character to be read or written. More...

PropWare::ErrorCode seek (const int32_t position)

PropWare::ErrorCode flush ()
Flush any modified data back to the SD card. More...

char get_char ()
Read a character from the file. More...

bool eof () const
Determine whether the read pointer has reached the end of the file. More...

PropWare::ErrorCode safe_peek (char &c)
Read a character from the file without incrementing the pointer. More...

char peek ()
Read a character from the file without incrementing the pointer. More...

PropWare::ErrorCode get_error () const
Get the latest error that occurred during an unsafe method call. More...

## Static Public Attributes

static const unsigned int MAX_FILENAME_LENGTH = 32

## Detailed Description

Read a file on a FAT 16 or FAT 32 storage device.

A file can be echoed to the terminal with a simple program such as

int main () {
const SD driver;
FatFS filesystem(&driver);
filesystem.mount();
return 0;
}

It can also be hooked up to the PropWare::Scanner class for line-by-line or formatted reading:

int main () {
const SD driver;
FatFS filesystem(&driver);
filesystem.mount();
char buffer[256];
fileScanner.gets(buffer, 256);
}
return 0;
}
Examples

Definition at line 79 of file fatfilereader.h.

## ◆ ErrorCode

 inherited
Enumerator
ENTRY_NOT_FILE

FatFile Error 0

FILENAME_NOT_FOUND

FatFile Error 1

Definition at line 38 of file fatfile.h.

## ◆ SeekDir

 stronginherited
Enumerator
BEG

beginning of the stream

CUR

current position in the stream

END

end of the stream

Definition at line 47 of file file.h.

## Constructor & Destructor Documentation

 PropWare::FatFileReader::FatFileReader ( FatFS & fs, const char name[], BlockStorage::Buffer & buffer = SHARED_BUFFER, const Printer & logger = pwOut )

Construct a new file instance.

Parameters
 [in] fs The filesystem is needed for opening the file [in] name Name of the file to open - it must exist in the current working directory (see issue 55 for opening from a relative or absolute path) [in] *buffer Address of a dedicated buffer that should be used for this file. If left as the NULL (the default), a shared buffer will be used. [in] logger This is only used for printing debug statements. Use of the logger is limited such that all references will be optimized out in normal application code

Definition at line 93 of file fatfilereader.h.

## ◆ close()

 virtual PropWare::ErrorCode PropWare::File::close ( )
virtualinherited

Close a file - a required step in any workflow that includes opening a file.

Returns
0 upon success, error code otherwise

Definition at line 74 of file file.h.

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ eof()

inherited

Determine whether the read pointer has reached the end of the file.

Returns
Returns true if the pointer points to the end of the file, false otherwise

Definition at line 75 of file filereader.h.

## ◆ exists() [1/2]

 bool PropWare::FatFile::exists ( ) const
inherited

Determine if a file exists (file does not have to be open)

Returns
True if the file exists, false otherwise

Definition at line 62 of file fatfile.h.

Here is the call graph for this function:

## ◆ exists() [2/2]

 bool PropWare::FatFile::exists ( PropWare::ErrorCode & err ) const
inherited

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
 [out] err It is possible for an error to occur

Definition at line 72 of file fatfile.h.

Here is the call graph for this function:

## ◆ flush() [1/2]

virtualinherited

Flush any modified data back to the SD card.

Returns
0 upon success, error code otherwise

Implements PropWare::File.

Definition at line 40 of file filereader.h.

## ◆ flush() [2/2]

 virtual PropWare::ErrorCode PropWare::File::flush ( )
pure virtualinherited

Flush any modified data back to the SD card.

Returns
0 upon success, error code otherwise

Here is the caller graph for this function:

## ◆ get_char()

virtualinherited

Read a character from the file.

Postcondition
If an error occurs, you can retrieve the error code via FileReader::get_error()
Returns
Character upon success, -1 otherwise

Implements PropWare::ScanCapable.

Definition at line 60 of file filereader.h.

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ get_error()

inherited

Get the latest error that occurred during an unsafe method call.

Methods such as FileReader::get_char() would normally throw an exception if an error occurred in a C++ program, but due to size constraints, exceptions are not used by PropWare. Therefore, any error that is occurs in a function that does not return ErrorCode simply saves the error to the internal state and returns a known value.

Returns
Most recent error code

Definition at line 115 of file filereader.h.

## ◆ get_name()

 const char* PropWare::FatFile::get_name ( ) const
inherited

Determine the name of a file.

Returns
Character array containing the file - DO NOT modify the array, it will modify the internals of the file instance

Definition at line 53 of file fatfile.h.

Here is the caller graph for this function:

## ◆ open()

virtual

Open the file.

Returns
0 upon success, error code otherwise

Implements PropWare::File.

Definition at line 100 of file fatfilereader.h.

Here is the call graph for this function:

## ◆ peek()

inherited

Read a character from the file without incrementing the pointer.

Postcondition
If an error occurs, you can retrieve the error code via FileReader::get_error()
Returns
Character upon success, -1 otherwise

Definition at line 99 of file filereader.h.

Here is the call graph for this function:

## ◆ safe_get_char()

 PropWare::ErrorCode PropWare::FatFileReader::safe_get_char ( char & c )
virtual

Read a character from the file.

Parameters
 [out] c Character from file will be stored into c
Returns
0 upon success, error code otherwise

Definition at line 115 of file fatfilereader.h.

## ◆ safe_peek()

 PropWare::ErrorCode PropWare::FileReader::safe_peek ( char & c )
inherited

Read a character from the file without incrementing the pointer.

Parameters
 [out] c Character from file will be stored into c
Returns
0 upon success, error code otherwise

Definition at line 86 of file filereader.h.

Here is the call graph for this function:

## ◆ seek() [1/2]

 PropWare::ErrorCode PropWare::File::seek ( const int32_t offset, const SeekDir way )
inherited

Sets the position of the next character to be read or written.

Parameters
 [in] offset Offset value, relative to the way parameter [in] way Starting position for the movement and direction of movement
Returns
0 upon success, error code otherwise

Definition at line 112 of file file.h.

Here is the caller graph for this function:

## ◆ seek() [2/2]

 PropWare::ErrorCode PropWare::File::seek ( const int32_t position )
inherited

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
 [in] position Absolute position to move the file position indicator

Definition at line 147 of file file.h.

Here is the call graph for this function:

## ◆ tell()

 int32_t PropWare::File::tell ( ) const
inherited

Obtain the value of the file position indicator.

Postcondition
The next byte to be read from the file

Definition at line 100 of file file.h.

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