User`s manual

160 digi.com File Systems
10.2.4.2.5 Reading Directories
The fat_ReadDir() function reads the next directory entry from the specified directory. A directory
entry can be a file, directory or a label. A directory is treated just like a file.
The first parameter specifies the directory; &dir is an open file handle. A directory is opened by a call to
fat_OpenDir() or by passing FAT_DIR in a call to fat_Open(). The second parameter, &dirent,
is a pointer to a directory entry structure to fill in. The directory entry structure must be declared in your
application, for example:
fat_dirent dirent;
Search Conditions
The last parameter, mode, determines which directory entry is being requested, a choice that is built from
a combination of the macros described below. To understand the possible values for mode, the first thing
to know is that a directory entry can be in one of three states: empty, active or deleted. This means you
must choose one of the default flags described below, or one or more of the following macros:
• FAT_INC_ACTIVE - include active entries. This is the default setting if other FAT_INC_* macros
are not specified; i.e., active files are included unless FAT_INC_DELETED, FAT_INC_EMPTY, or
FAT_INC_LNAME is set.
• FAT_INC_DELETED - include deleted entries
• FAT_INC_EMPTY - include empty entries
• FAT_INC_LNAME - include long name entries (this is included for completeness, but is not used since
long file names are not supported)
The above macros narrow the search to only those directory entries in the requested state. The search is
then refined further by identifying particular attributes of the requested entry. This is done by choosing one
or more of the following macros:
• FATATTR_READ_ONLY - include read-only entries
• FATATTR_HIDDEN - include hidden entries
• FATATTR_SYSTEM - include system entries
• FATATTR_VOLUME_ID - include label entries
• FATATTR_DIRECTORY - include directory entries
• FATATTR_ARCHIVE - include modified entries
Including a FATATTR_* macro means you do not care whether the corresponding attribute is turned on or
off. Not including a FATATTR_* macro means you only want an entry with that particular attribute turned
off. Note that the FAT system sets the archive bit on all new files as well as those written to, so including
FATATTR_ARCHIVE in your mode setting is a good idea.
For example, if mode is (FAT_INC_ACTIVE) then the next directory entry that has all of its attributes
turned off will be selected; i.e., an entry that is not read only, not hidden, not a system file, not a directory
or a label, and not archived. In other words, the next writable file that is not hidden, system or already
archived is selected.
fat_ReadDir(&dir, &dirent, mode);