FileMgr::BuildFileList

Defined in: C4Files.h

Enumerates the files in a given directory.

Prototype

static void BuildFileList(const char *directory, List<FileReference> *list, BuildProc *proc = &DefaultFilter, void *cookie = nullptr);

Parameters

`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.
`list`	A pointer to an existing list object which is to contain the `FileReference` objects.
`proc`	A pointer to an optional filter function.
`cookie`	The value that is passed to the `cookie` parameter of the filter function.

Description

The BuildFileList 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 BuildFileList 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::Purge function or by destroying the List object itself.

If a filter function is specified by the proc 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 BuildProc type is defined as follows.

typedef bool BuildProc(const char *name, unsigned long flags, 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 BuildFileList function. The flags associated with a file can be a combination (through logical OR) of the following bit values.

`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 should return false to indicate that the file should be skipped.

If no filter function is specified, then the default filter function 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.