EAFileDirectory

Introduction

EAFileDirectory provides directory reading functionality. This is useful for both tools and runtime applications, particularly during development time in the case of runtime applications. With

Directory reading is implemented via two means: low level FindFirstEntry / FindNextEntry functions and a high level DirectoryIterator class.

EntryFindData* EntryFindFirst(const char16_t* pDirectory, const char16_t* pFilterPattern = NULL);
bool           EntryFindNext(EntryFindData* pData);
void           EntryFindFinish(EntryFindData* pData);
class DirectoryIterator
{
    bool Read(const char16_t* pDirectory, EntryList& entryList, 
               const char16_t* pFilterPattern, int nDirectoryEntryFlags);

    bool ReadRecursive(const char16_t* pBaseDirectory, EntryList& entryList, 
                        const char16_t* pFilterPattern, int nDirectoryEntryFlags, 
                        bool bIncludeBaseDirectory);
};

Details for the above interfaces can be found below in the Interface section or in the EAFileDirectory.h file. See also EAFileBase for enumerations that are pertinent to EAFileDirectory.

Example usage

Low level functionality:

EntryFindData* p;


for(p = EntryFindFirst(L"/somedir/", L"*.html"); p; p = EntryFindNext(p))
    printf("%ls", p->mName);

EntryFindFinish(p);

High level functionality:

DirectoryIterator dir;
EntryList         entryList;
 
dir.ReadRecursive(L"/somedir/", entryList,  L"*.html");

for(EntryList::iterator it(entryList.begin()), itEnd(entryList.end()); it != itEnd; ++it)
{
    const DirectoryIterator::Entry& entry = *it;

    printf("%ls\n", entry.msName.c_str());
}

Interface

Low level functionality:

/// EntryFindFirst
///
/// This function returns an internally allocated EntryFindData* or returns NULL. 
/// You must call EntryFindFinish to free the EntryFindData*; do not attempt to 
/// delete the pointer yourself. This function allocates memory from the global
/// heap; the amount of memory allocated is relative to the number of matching 
/// entries in the given directory.
///
/// Note that this function and all other functions in the EAFile/EADirectory system requires
/// a directory path name that ends in a path separator. This is by design as it simplifies
/// the specification of and manipulation of paths.
///
EntryFindData* EntryFindFirst(const char16_t* pDirectory, const char16_t* pFilterPattern = NULL);


/// EntryFindNext
///
/// Input is the 'EntryFindData*' returned from EntryFindFirst. 
/// You must call EntryFindFinish to free the EntryFindData*; 
/// do not attempt to delete the pointer yourself.
///
EntryFindData* EntryFindNext(EntryFindData* pData);


/// EntryFindFinish
///
/// Input is the 'EntryFindData*' returned from EntryFindFirst. 
/// This is the only safe way to free a EntryFindData*.
///
void EntryFindFinish(EntryFindData* pData);

High level functionality:

// Note that Entry and EntryList will be changed in the future to avoid memory allocation.

class DirectoryIterator
{
public:
    /// Entry
    /// 
    /// Represents a single file system directory entry, such as a file or a directory.
    ///
    struct Entry
    {
        Entry(DirectoryEntry entry = kDirectoryEntryNone, const char16_t* pName = NULL);
        DirectoryEntry mType;     /// Either kDirectoryEntryFile or kDirectoryEntryDirectory.
        String16       msName;    /// This may refer to the directory or file name alone, 
    };                            /// or may be a full path. It depends on the documented use.

    typedef eastl::list EntryList;

    /// Read
    ///
    /// Returns a list of the directory entries that match the input criteria.
    /// This function will not store the results of this read internally.
    /// This function is not recursive; it will not read the contents of subdirectories.
    /// The returned list contains only the entry name and not the full path to that
    /// entry. You can prepend the base path to get the full path.
    /// The returned list will not contain special directory values "." and "..".
    /// Note that this function and all other functions in the EAFile/EADirectory system requires
    /// a directory path name that ends in a path separator. This is by design as it simplifies
    /// the specification of and manipulation of paths.
    ///
    bool Read(const char16_t* pDirectory, EntryList& entryList, const char16_t* pFilterPattern = NULL, 
               int nDirectoryEntryFlags = kDirectoryEntryFile);

    /// ReadRecursive
    ///
    /// Returns a list of all paths that match the input criteria.
    /// This function can be used both as a file system enumeration function and 
    /// as a search function.
    /// As indicated in the name, this function is recursive. It will search all 
    /// subdirectories recursively for matching data. The returned list is in
    /// an order consistent with a depth-first search. The returned list contains 
    /// partial paths to each entry; you can prepend the base path to get the full path.
    /// The returned list will not contain special directory values "." and "..".
    /// Note that this function and all other functions in the EAFile/EADirectory system requires
    /// a directory path name that ends in a path separator. This is by design as it simplifies
    /// the specification of and manipulation of paths.
    ///
    bool ReadRecursive(const char16_t* pBaseDirectory, EntryList& entryList, 
                       const char16_t* pFilterPattern = NULL, int nDirectoryEntryFlags = kDirectoryEntryFile, 
                       bool bIncludeBaseDirectory = true);
};