FileEnum()

word	FileEnum( /* returns number of files returned */
        FileEnumParams		* params,			/* described below */
        MemHandle		* bufCreated,			/* FileEnum will allocate a return-
						 * buffer block & write its handle
						 * here */

        word		* numNoFit);				/* Number of files not handled is
						 * written here */

This routine is used to examine all the files in a directory. The routine can filter the files by whether they have certain extended attributes. It creates a buffer and writes information about the files in this buffer. This routine can be called in many different ways; full details are available.

Structures: FileEnum() uses several structures and enumerated types. They are shown below; the detailed description of the structures follows.

        	/* Types, values, and structures passed
 * to the FileEnum() routine: */

        typedef enum /* word */ {
FESRT_COUNT_ONLY,
FESRT_DOS_INFO,
FESRT_NAME,
FESRT_NAME_AND_ATTR

        } FileEnumStandardReturnType;
        typedef enum /* word */ {
FESC_WILDCARD

        } FileEnumStandardCallback;
        	/* Types, values, and structures returned
 * by the FileEnum() routine: */

        typedef struct {
FileAttrs 			DFIS_attributes;
FileDateAndTime 			DFIS_modTimeDate;
dword 			DFIS_fileSize;
FileLongName 			DFIS_name;
DirPathInfo 			DFIS_pathInfo;

        } FEDosInfo;
        typedef struct _FileEnumCallbackData {
FileExtAttrDesc 			FECD_attrs[1];

        } FileEnumCallbackData;
        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;

Most of the information passed to FileEnum() is contained in a FileEnumParams structure. The fields of the structure are as follows:

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 is a pointer to an array of FileExtAttrDesc structures. The last structure should have its FEA_attr field set to FEA_END_OF_LIST. The array specifies what information will be returned by FileEnum() . The FileExtAttrDesc structure is used in a slightly different way than usual. Every file will have an entry in the return buffer; this entry will contain all the extended attribute information requested. Each FileExtAttrDesc structure will specify where in that entry its information should be written. The FEAD_value field should contain only an offset value; the extended attribute will be written at that offset into the entry. (You can specify an offset by casting an integer value to type void * .) The FEAD_size value specifies how long the return value can be. 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 is a pointer to an array of FileExtAttrDesc structures. The last structure should have its FEA_attr field set to FEA_END_OF_LIST. FileEnum() will automatically filter out and ignore all files whose attributes do not match the ones specified by this array. For attributes that are word-sized records, FEAD_value.offset holds the bits that must be set, and FEAD_value.segment holds the bits that must be clear. For byte-sized flags, FEAD_value.offset.low contains the flags that must be set, and FEAD_value.offset.high contains flags that must be clear. Byte- and word-sized non-flag values are stored in FEAD_value.offset . For all other values, FEAD_value holds a pointer to the exact value to match, and FEAD_size specifies the length of that value (in bytes). 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_bufS: ize This specifies the maximum number of entries to be returned in the buffer. If you do not want to set a limit, pass the constant FE_BUFSIZE_UNLIMITED. The buffer will be grown as necessary.
FEP_skipCount: This 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. For example, if you only wanted to examine ten files at a time, you would set FEP_bufSize to ten and FEP_skipCount to zero. FileEnum() would return the data for the first ten files which match the search criteria. After processing the returned data, if there were any files left over, you could call FileEnum() again, this time with FEP_skipCount set to ten; FileEnum() would handle the next ten matching files and return the data about them. 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 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 should be declared _pascal. It is passed three arguments: a pointer to the FileEnumParams structure, a pointer to the current stack frame (which is used by some assembly callback routines), and a pointer to an array of FileExtAttrDesc structures. These structures are all the attributes required either for return, matching, or callback (see FEP_callbackAttrs below), with the information for the current file filled in; you can search through them directly for the information you want, or you can call FileEnumLocateAttr() to search through this array. 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.)
FEP_callbackAttrs: This is a pointer to an array of FileExtAttrDesc structures. The last structure should have its FEA_attr field set to FEA_END_OF_LIST. 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 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.

The FileEnumStandardReturnType enumerated type has the following values; they are used in conjunction with the FEP_returnAttrs field of the FileEnumParams structure.

FESRT_COUNT_ONLY: FileEnum() will not allocate any memory and will not 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 (DFIS_pathInfo ) 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.

See Also: FileEnumLocateAttr(), FileEnumWildcard().

Include: fileEnum.h