FileMgr::BuildFileMap

Enumerates the files in a given directory.

static void BuildFileMap(const char *directory, Map<FileReference> *map, FileMapFilter *filter = &DefaultFilter, const void *cookie = nullptr);

directory	A pointer to the name of the directory for which files should be enumerated. If a path name is specified, it is interpreted relative to the application. Multiple directory names should be separated by single forward slash characters (/), but the last directory name in the path should not be followed by a slash.
map	A pointer to an existing map object which is to contain the FileReference objects.
filter	A pointer to a filter function. This can be omitted, but it cannot be nullptr.
cookie	The value that is passed to the cookie parameter of the filter handler.

The BuildFileMap function enumerates the files in the directory given by the directory parameter and instantiates a FileReference object for each file in the directory. These objects are placed into the list given by the list parameter.

One typically calls BuildFileMap to obtain a list of files in a particular directory and then iterates through the list to examine each file individually. When the list of FileReference objects is no longer needed, the memory for each of the objects should be released. This can be done by calling the List::PurgeList function or by destroying the List object itself.

If a filter function is specified by the filter parameter, then it is called for each file as the list is being built to determine whether the file should be included in the list. The FileMapFilter type is defined as follows.

typedef bool FileMapFilter(const char *name, uint32 flags, const void *cookie);

The name parameter of the filter function recieves a pointer to the file name, the flags parameter receives the flags associated with the file, and the cookie parameter receives the value passed to the cookie parameter of the BuildFileMap function. The flags associated with a file can be a combination (through logical OR) of the following constants.

kFileDirectory	The file reference represents a directory.
kFileInvisible	The file is invisible.

The filter function should return true to indicate that the file should be included in the file list, and it should return false to indicate that the file should be skipped.

If no filter function is specified, then the default filter function FileMgr::DefaultFilter is used. The default filter function returns false if the kFileInvisible flag is set or if the file name begins with a period, and returns true otherwise. The File Manager also defines two additional filter functions named FileMgr::FileFilter and FileMgr::DirectoryFilter. Like the default filter function, both of these functions return false if the kFileInvisible flag is set or if the file/directory name begins with a period. The FileMgr::FileFilter function returns false if the kFileDirectory flag is set, and the FileMgr::DirectoryFilter function returns false if the kFileDirectory flag is not set.