| 
  • If you are citizen of an European Union member nation, you may not use this service unless you are at least 16 years old.

  • Stop wasting time looking for files and revisions. Connect your Gmail, DriveDropbox, and Slack accounts and in less than 2 minutes, Dokkio will automatically organize all your file attachments. Learn more and claim your free account.

View
 

SdFile Functions

Page history last edited by Matthew Seal 9 years, 3 months ago

Below are some useful functions that SdFiles can use. This allows you to search around the Sd card and determine what the contents are.

 

void dirName(const dir_t& dir, char* name)

uint8_t openRoot(SdVolume* vol)

void ls(uint8_t flags, uint8_t indent)

uint8_t makeDir(SdFile* dir, const char* dirName)

uint8_t remove(void)

uint8_t remove(SdFile* dirFile, const char* fileName)

uint8_t rmDir(void)

uint8_t rmRfStar(void)

int16_t read(void* buf, uint16_t nbyte)

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

uint8_t open(SdFile* dirFile, uint16_t index, uint8_t oflag)

uint8_t seekSet(uint32_t pos)

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)

int8_t readDir(dir_t* dir)

uint8_t sync(void)

uint8_t timestamp(uint8_t flags, uint16_t year, uint8_t month,
         uint8_t day, uint8_t hour, uint8_t minute, uint8_t second)

 

 

Detailed descriptions are below:

 

 

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

 *
 * param[in] dir The directory structure containing the name.
 * param[out] name A 13 byte char array for the formatted name.
 */
void dirName(const dir_t& dir, char* name)

 

 

/**
 * Open a volume's root directory.
 *
 * param[in] vol The FAT volume containing the root directory to be opened.
 *
 * return 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 openRoot(SdVolume* vol)

 

 

/** List directory contents to Serial.
 *
 * \param[in] flags The inclusive OR of
 *
 * LS_DATE - %Print file modification date
 *
 * LS_SIZE - %Print file size.
 *
 * LS_R - Recursive list of subdirectories.
 *
 * \param[in] indent Amount of space before file name. Used for recursive
 * list to indicate subdirectory level.
 */
void ls(uint8_t flags, uint8_t indent)

 

 

/** Make a new directory.
 *
 * param[in] dir An open SdFat instance for the directory that will containing
 * the new directory.
 *
 * param[in] dirName A valid 8.3 DOS name for the new directory.
 *
 * return 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, \a dir is not a
 * directory, \a dirName is invalid or already exists in \a dir.
 */
uint8_t makeDir(SdFile* dir, const char* dirName)

 

 

/**
 * 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".
 *
 * return 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 remove(void)

 

 

/**
 * Remove a file.
 *
 * The directory entry and all data for the file are deleted.
 *
 * param[in] dirFile The directory that contains the file.
 * param[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".
 *
 * return 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,
 * \a dirFile is not a directory, \a fileName is not found
 * or an I/O error occurred.
 */
uint8_t remove(SdFile* dirFile, const char* fileName)

 

 

/** 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".
 *
 * return 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 rmDir(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().
 *
 * return The value one, true, is returned for success and
 * the value zero, false, is returned for failure.
 */
uint8_t rmRfStar(void)

 

 

/**
 * Read data from a file starting at the current position.
 *
 * param[out] buf Pointer to the location that will receive the data.
 *
 * param[in] nbyte Maximum number of bytes to read.
 *
 * return For success read() returns the number of bytes read.
 * A value less than \a 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 read(void* buf, uint16_t nbyte)

 

 

/**
 * Open a file or directory by name.
 *
 * param[in] dirFile An open SdFat instance for the directory containing the
 * file to be opened.
 *
 * param[in] fileName A valid 8.3 DOS name for a file to be opened.
 *
 * param[in] oflag Values for \a 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.
 *
 * return 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, \a difFile is not
 * a directory, \a fileName is invalid, the file does not exist
 * or can't be opened in the access mode specified by oflag.
 */
uint8_t open(SdFile* dirFile, const char* fileName, uint8_t oflag)

 

 

/**
 * Open a file by index.
 *
 * param[in] dirFile An open SdFat instance for the directory.
 *
 * param[in] index The \a index of the directory entry for the file to be
 * opened.  The value for \a index is (directory file position)/32.
 *
 * param[in] oflag Values for \a 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 open(SdFile* dirFile, uint16_t index, uint8_t oflag)

 

 

/**
 * Sets a file's position.
 *
 * param[in] pos The new position in bytes from the beginning of the file.
 *
 * return The value one, true, is returned for success and
 * the value zero, false, is returned for failure.
 */
uint8_t seekSet(uint32_t pos)

 

 

/**
 * 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.
 *
 * param[in] buf Pointer to the location of the data to be written.
 *
 * param[in] nbyte Number of bytes to write.
 *
 * return For success write() returns the number of bytes written, always
 * \a 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.
 *
 */
int16_t write(const void* buf, uint16_t nbyte)

 

/**
 * Write a string to a file. Used by the Arduino Print class.
 *
 * Use SdFile::writeError to check for errors.
 */
void write(const char* str)

 


/**
 * Write a PROGMEM string to a file.
 *
 * Use SdFile::writeError to check for errors.
 */
void write_P(PGM_P str)

 

 

/**
 * Write a PROGMEM string followed by CR/LF to a file.
 *
 * Use SdFile::writeError to check for errors.
 */
void writeln_P(PGM_P str)

 

 

/**
 * Read the next directory entry from a directory file.
 *
 * param[out] dir The dir_t struct that will receive the data.
 *
 * return 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 readDir(dir_t* dir)

 

 

/**
 * The sync() call causes all modified data and directory fields
 * to be written to the storage device.
 *
 * return 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 sync(void)

 

 

/**
 * Set a file's timestamps in its directory entry.
 *
 * param[in] flags Values for \a 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.
 *
 * param[in] year Valid range 1980 - 2107 inclusive.
 *
 * param[in] month Valid range 1 - 12 inclusive.
 *
 * param[in] day Valid range 1 - 31 inclusive.
 *
 * param[in] hour Valid range 0 - 23 inclusive.
 *
 * param[in] minute Valid range 0 - 59 inclusive.
 *
 * param[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.
 *
 * note
 * Modify and access timestamps may be overwritten if a date time callback
 * function has been set by dateTimeCallback().
 *
 * return The value one, true, is returned for success and
 * the value zero, false, is returned for failure.
 */
uint8_t timestamp(uint8_t flags, uint16_t year, uint8_t month,
         uint8_t day, uint8_t hour, uint8_t minute, uint8_t second)

 

 

 

Comments (0)

You don't have permission to comment on this page.