The File System: 5.5 Files: FileEnum()

FileEnum(), FileEnumLocateAttr(), FileEnumWildcard(), FileEnumAttrs, FileEnumSearchFlags, FileEnumStandardReturnType, FEDosInfo, FENameAndAttr, FileEnumCallbackData

You may sometimes need to perform an action on every file that matches certain criteria. For these situations, the file system provides the routine FileEnum() . FileEnum() can be called in two ways. The usual way is to have FileEnum() provide certain information about every file in a directory (or every file of a given type); when called, FileEnum() will allocate a buffer and fill it with data structures, one for each matching file. Less commonly, you can have FileEnum() call a callback routine for every file which matches certain criteria; this callback routine can take a broader range of actions.

You should not often need to use the FileEnum() routine. The most common time that applications would need this functionality is when they present a list of the files in a directory to the user. The GenFileSelector object provides this functionality, making all necessary calls to FileEnum() transparently to both the user and the geode. Note that the document control objects automatically create and manipulate a file selector when appropriate. For further information, see the FileSelector object chapter.

FileEnum() takes the following arguments:

A pointer to a FileEnumParams structure (see below). The data in this structure will tell FileEnum() what to do.
A pointer to a MemHandle variable. FileEnum() will allocate a memory block to hold information about the files, and will write the block's handle to this location.
A pointer to a word variable. If FileEnum() was unable to fit information about all the files into the block passed, it will write the number of files not handled into this variable.

FileEnum() returns the number of files which were returned in the buffer.

The FileEnumParams structure specifies how FileEnum() should perform. The structure is defined as follows. A summary of each field's role follows; for full details, see the reference entry for FileEnum() .

typedef struct _FileEnumParams {
	FileEnumSearchFlags 				FEP_searchFlags;
	FileExtAttrDesc *				FEP_returnAttrs;
	word 				FEP_returnSize;
	FileExtAttrDesc *				FEP_matchAttrs;
	word 				FEP_bufSize;
	word 				FEP_skipCount;
	word _pascal (*FEP_callback) 
		(struct _FileEnumParams *					params,
		 FileEnumCallbackData *					fecd,
		 word 					frame);
	FileExtAttrDesc *				FEP_callbackAttrs;
	dword 				FEP_cbData1;
	dword 				FEP_cbData2;
	word 				FEP_headerSize;
} FileEnumParams;

FEP_searchFlags: This is a byte-length flag field. The flags are of type FileEnumSearchFlags (described below). These flags specify which files at the current location will be examined by FileEnum() . They also specify such things as whether a callback routine should be used.
FEP_returnAttrs: This field specifies what information is wanted about the files. It is a pointer to an array of FileExtAttrDesc structures (see FEA_MULTIPLE ). The attributes will be written to the return buffer; each file will have an entry, containing all the attributes requested for that file. You can also request certain return values by setting FEP_returnAttrs to equal a member of the FileEnumStandardReturnType (again, by casting the FileEnumStandardReturnType value to type void * ). The FileEnumStandardReturnType enumerated type is described later in this section.
FEP_returnSize: This is the size of each entry in the returned buffer. If a standard return type or an array of FileExtAttrDesc structures was passed, each entry in the returned buffer will contain all the extended attribute information requested for that file.
FEP_matchAttrs: This field specifies which files should be enumerated by FileEnum() . It is a pointer to an array of FileExtAttrDesc structures (see FEA_MULTIPLE ). These structures specify values for certain extended attributes. Only those files whose extended attributes match these will be enumerated. If you do not want to filter out any files in the working directory, or if you will use the callback routine to filter the files, pass a null pointer in this field.
FEP_bufsize: This field specifies the maximum number of entries to be returned in the buffer. If you do not want to set a limit, pass the constant FEP_BUFSIZE_UNLIMITED. The buffer will be grown as necessary.
FEP_skipCount: This field contains the number of matching files to be ignored before the first one is processed. It is often used in conjunction with FEP_bufSize to examine many files a few at a time. Each time FileEnum() is called, you can enumerate a certain number of files; by adjusting the skip count each time, you can start each enumeration where the previous one ended. In this way you could walk through all the matching files in the directory. Note that if the FileEnumSearchFlags bit FESF_REAL_SKIP is set (in FEP_searchFlags ), the first files in the directory will be skipped before they are tested to see if they match. This is faster, since the match condition won't have to be checked for the first files in the directory.
FEP_callback: This field holds a pointer to a Boolean callback routine. The callback routine can check to see if the file matches some other arbitrary criteria. The callback routine is called for any files which match all the above criteria. It can then decide whether to enumerate the file however it wishes. The callback routine should be declared _pascal . If the file should be accepted by FileEnum() , the callback should return true ; otherwise it should return false . You can also instruct FileEnum() to use one of the standard callback routines by passing a member of the FileEnumStandardCallback enumerated type. In this case, FEP_callbackAttrs is ignored; FileEnum() will automatically pass the appropriate information to the callback routine. (Note that if the FESF_CALLBACK bit of the FEP_searchFlags field is not set, the FEP_callback field is ignored.) The callback routine may not call any routines which are in movable memory at the time FileEnum() is called, except for routines which are in the same resource as the callback routine.
FEP_callbackAttrs: This field specifies what additional attributes should be read for the callback routine. This field is a pointer to an array of FileExtAttrDesc structures (see FEA_MULTIPLE ). The array will be filled in with the appropriate information for each file before the callback routine is called. Note that if the FESF_CALLBACK bit of the FEP_searchFlags is not set, the FEP_callbackAttrs is ignored. If you do not need any attributes passed to the callback routine, set this field to be a null pointer.
FEP_cbData1 , FEP_cbData2: These are dword-length fields. Their contents are ignored by FileEnum() ; they are used to pass information to the callback routine. If you do not call a standard callback routine, you may use these fields any way you wish.
FEP_headerSize: If the flag FESF_LEAVE_HEADER is set, FileEnum() will leave an empty header space at the beginning of the return buffer. The size of the header is specified by this field. If the flag FESF_LEAVE_HEADER is clear, this field is ignored.

The first field of the FileEnumParams structure, FEP_searchFlags , is a word-length record containing FileEnumSearchFlags . The following flags are available:

FESF_DIRS: Directories should be examined by FileEnum() .
FESF_NON_GEOS: Non-GEOS files should be examined by FileEnum() .
FESF_GEOS_EXECS: GEOS executable files should be examined by FileEnum() .
FESF_GEOS_NON_EXECS: GEOS non-executable files (e.g., VM files) should be examined by FileEnum() .
FESF_REAL_SKIP: If a skip count of n is specified, the first n files will be skipped regardless of whether they matched the attributes passed. In this case, FileEnum() will return the number of files passed through in order to get enough files to fill the buffer; the return value can thus be the real-skip count for the next pass.
FESF_CALLBACK: FileEnum() should call a callback routine to determine whether a file should be accepted.
FESF_LOCK_CB_DATA: This flag indicates that the FileEnumParams fields FEP_callback1 and FEP_callback2 are far pointers to movable memory that must be locked before FileEnum() is called.
FESF_LEAVE_HEADER: If set, FileEnum() should leave an empty header space at the start of the return buffer. The size of this buffer is specified by the FEP_headerSize field.

You can specify precisely which data you want about each file and in which arrangement it should be returned. However, for most purposes, you can get enough information by requesting one of the standard return types. If you pass a member of FileEnumStandardReturnType in FEP_returnAttrs , FileEnum() will write an array of structures to the return buffer; each file will have one such structure. The structures are shown below in Standard FileEnum() Return Structures . FileEnumStandardReturnType has the following values:

FESRT_COUNT_ONLY: FileEnum() will not allocate any memory or return data about files; instead, it will simply return the number of files which match the specified criteria.
FESRT_DOS_INFO: FileEnum() will return an array of FEDosInfo structures. These structures contain basic information about the file: its virtual name, size, modification date, DOS attributes, and path information (as a DirPathInfo record).
FESRT_NAME: FileEnum() will return an array of FileLongName strings, each one of which is FILE_LONGNAME_BUFFER_SIZE characters long; every one of these will contain a file's virtual name followed by a null terminator.
FESRT_NAME_AND_ATTR: FileEnum() will return an array of FENameAndAttr structures, each one of which contains a file's DOS attributes and virtual name.

The FEDosInfo structure includes a word-sized record which describes the file's position relative to the standard paths. It contains the following fields:

DPI_EXISTS_LOCALLY: This bit is set if the file exists in a directory under the primary tree.
DPI_ENTRY_NUMBER_IN_PATH: This is the mask for a seven-bit field whose offset is DPI_ENTRY_NUMBER_IN_PATH_OFFSET.
DPI_STD_PATH: This is the mask for an eight-bit field whose offset is DPI_STD_PATH_OFFSET. If the file is in a standard path, this field will contain a StandardPath constant for a standard path containing the file. This need not be the "closest" standard path; for example, if the file is in the "World" directory, this constant might nevertheless be SP_TOP.

Code Display 17-2 Standard FileEnum() Return Structures

/* These structures are the standard FileEnum() return types. You can also
 * instruct FileEnum() to return any arbitrary extended attribute information.
 */

typedef struct {			/* These are returned if you specify FESRT_DOS_INFO */
    FileAttrs 		FEDI_attributes;			/* File's DOS attributes; 
					 * see  Getting and Setting Information about a Byte File */
    FileDateAndTime 		FEDI_modTimeDate			/* Last modification time; see  FEA_MODIFICATION */
    dword 		FEDI_fileSize;			/* Size of file (in bytes) */
    FileLongName		FEDI_name;			/* File's virtual name; null-terminated */
    DirPathInfo 		FEDI_pathInfo;			/* PathInfo structure, described above */
} FEDosInfo;

typedef struct{ 			/* These are returned if you specify FESRT_NAME_AND_ATTR */
    FileAttrs 		FENAA_attributes;			/* File's DOS attributes; 
					 * see  Getting and Setting Information about a Byte File */
    FileLongName 		FENAA_name;			/* File's virtual name; null-terminated */
} FENameAndAttr;

There is currently one standard callback routine provided. This routine, FileEnumWildcard() , rejects all files whose names don't match a wildcard string. To call this routine, set FEP_callback as follows:

enumParams.FEP_callback = (void *) FESC_WILDCARD;

FEP_cbData1 should be a pointer to a null-terminated wildcard string. In this string, "*" denotes a sequence of zero or more of any character, and "?" denotes any one character; all other characters represent themselves. If a file's virtual name matches the wildcard string, information about it will be returned by FileEnum() . If the lowest byte of FEP_cbData2 is non-zero, the comparison will be case-insensitive; otherwise, it will be case-sensitive. (The other bytes of FEP_cbData2 are ignored.) This is different from standard DOS wildcarding; for example, the name "doc*." matches any file that begins with the letters "doc" and ends with a period, whereas a DOS wildcard string "doc*." would match only those files whose name start with "doc" and which have no extension.

If you're writing your own callback routine, you may wish to use the FileEnumLocateAttr() utility routine. This routine searches a FileExtAttrDesc array (as passed to FileEnum() callbacks), and will search the array for a file matching a particular attribute.

GEOS SDK TechDocs |

5.4 File Utilities | Next:

5.6 Bytewise File Operations