common file operations

Description

The file must be opened to use the following functions which can be used on ‘normal’- and ‘recSet’ Files:
bool() – returns true if the file exists.
write() – writes bytes from a buffer to the file starting at the current index pointer position. returns the number of bytes successfully written.
read() – reads from the file (beginning at the position pointers index) into the buffer
position() – read / write index pointing at the next byte within the file ( or record set) to be written / read from at the next read/write operation. In a record set file the position() refers to the beginning of the current record (not to the start of the file)
seek() – places the position pointer at the given index within the file (or within the record set, respectively).
available() – number of bytes that can be read/written at the next read/write operation.
– for normal files: this is the number of bytes until the end of the file.
– for record-set files: it returns the number of bytes till the end of the current record.
size() – returns the size of
– for normal files: size of the the entire reserved space in flash for this file
– for record set files: number of written records x size of one record; = the number of bytes that can be read from this file
erase() – erases the content of the file but keeps its size & space in flash, its name and its type (normal or rec-set)
getWriteCounter() – returns the number of bytes written into a file-object, even before it was actually created in the serial flash IC.

Syntax

if( file ) - boolean operator file.write( buf, length ); file.read( buf, length ); file.position(); file.seek( index ); file.available() file.size() file.erase();

Parameters

file – object of class SerialFlashFile
buf – void* – pointer to an array of data; the read or write buffer (e.g. uint8_t buf[128] )
length – uint32_t – number of byte to read/write
index – uint32_t – index of the new position within the file to place the r/w-pointer

Returns

write(): returns (uint32_t) the number of bytes that could successfully be written into the file
read(): returns (uint32_t) the number of bytes that could successfully be read from the file into the buffer (buf)
position(): returns (uint32_t) the current index at which the r/w pointer is pointing at.
seek(): returns nothing (void)
available(): returns (uint32_t) the number of remaining bytes till the end of the file / recordset, respectively.
getWriteCounter(): (uint32_t) the number bytes written into the file object (eg. to determine the required size before creating)

Example Code

#include "SerialFlash.h"
void setup()
{
  char c;
  while(!Serial);
  SerialFlash.begin();
  if( SerialFlash.create("myFile.txt", 1024) == false )
    Serial.println("Normal file could NOT be created");

  SerialFlashFile file = SerialFlash.open("myFile.txt");
  while((file.read(&c, 1) > 0) && (c != 255))
    Serial.write(c);

  file.seek( file.position() -1 ); // adjust the r/w pointer
  file.write("new data\n", 9); 
}
void loop () 
{ }

^{see examples in the Arduino menu: File -> Examples -> SerialFlash}

Notes and Warnings

Normal files like in the example above don’t need to be closed, but record-set files have to be closed() which marks all successfully written records in the file as complete and valid. If the devices is switched off while a record-set file is open, the current (open) record will be lost / ‘invalided’.

Record set files:
write() operations on record set files only write till the end of the current record. Then newRec() has to be called to append a new record and start writing into this new record. If it is written into a new file without any newRecords created yet, the write function would automatically create the first record and starts writing into it. An attempt to write into a finished record will fail, returning 0.
read() operations on record set file read over the boundaries of the records. Which makes it possible to read / transfer files in one go. Bad records will automatically be left out so that only valid data will be read.
position(), seek() and available() on record set files are understood to act within the current record. seek(0) for example would set the r/w-index to the first byte within the current record (not the begin of the file). available() returns the space until the end of the current record. See the record set functions for ways to move between record sets (goFirstRec(), goNextRec() etc.).