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

  • You already know Dokkio is an AI-powered assistant to organize & manage your digital files & messages. Very soon, Dokkio will support Outlook as well as One Drive. Check it out today!

View
 

SdFile Functions

Page history last edited by Matthew Seal 12 years, 11 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.