pszFileSpec (PSZ) - input
The name component can contain global file name characters.
phdir (PHDIR) - in/out
The values that can be specified for the handle are shown in the following list:
HDIR_CREATE (0xFFFFFFFF)
flAttribute (ULONG) - input
The bit values are shown in the following list:
31-14
Bits 8 through 13 are "Must-Have" flags. These allow you to obtain files that definitely have the given attributes. For example, if the Must-Have Subdirectory bit is set to 1, then all returned items are subdirectories.
If a Must-Have bit is set to 1, and the corresponding May-Have bit is set to 0, no items are returned for that attribute.
The attribute FILE_NORMAL (0x00000000) can be used to include files with any of the above bits set.
flAttribute cannot specify the volume label. Volume labels are queried using DosQueryFSInfo.
pfindbuf (PVOID) - in/out
The result buffer from DosFindFirst should be less than 64KB.
Address of the directory search structures for file object information Levels 1 through 3. The structure required for pfindbuf is dependent on the value specified for ulInfoLevel. The information returned reflects the most recent call to DosClose or DosResetBuffer.
For Level 1 File Information (ulInfoLevel == FIL_STANDARD) :
The oNextEntryOffset field indicates the number of bytes from the beginning of the current structure to the beginning of the next structure. When this field is 0, the last structure has been reached.
The cbList field contains the size, in bytes, of the file's entire EA set on disk. You can use this field to calculate the maximum size of the buffer needed for Level 3 file information. The size of the buffer required to hold the entire EA set is less than or equal to twice the size of the EA set on disk.
On output, pfindbuf contains a structure with a set of records, each aligned on a doubleword boundary. These records represent the directory entry and associated EAs for the matched file object. pfindbuf has the following format:
The EAOP2 data structure occurs only once in the pfindbuf buffer. The rest of these records are repeated for the remainder of the file objects found.
When buffer overflow occurs, cbList contains the size on disk of the entire EA set for the file, even if only a subset of its attributes was requested. The size of the buffer required to hold the EA set is less than or equal to twice the size of the EA set on disk. If no error occurs, cbList includes the pad bytes (for doubleword alignment) between FEA2 structures in the list.
If a particular attribute is not attached to the object, pfindbuf has an FEA2 structure containing the name of the attribute, and the length value is 0.
The GEA2 list contained inside pfindbuf during a Level 3 DosFindFirst and DosFindNext call is not "read-only"; it is used by OS/2. When the function returns, the list is restored to it's original state, but inside the function, the list is manipulated by OS/2. This is of concern to a multithreaded application, where two different threads might use the same GEA2 list as input. If one thread calls DosFindFirst or DosFindNext while another thread is inside DosFindFirst or DosFindNext, the second thread will fail with a return code of ERROR_BAD_FORMAT.
cbBuf (ULONG) - input
pcFileNames (PULONG) - in/out
Input
ulInfoLevel (ULONG) - input
Possible values are:
The structures described in pfindbuf indicate the information returned for each of these levels.
Regardless of the level specified, a DosFindFirst request (and an associated DosFindNext) request on a handle returned by DosFindFirst) always includes Level 1 information as part of the information that is returned; however, when Level 1 information is specifically requested, and flAttribute specifies hidden files, system files, or subdirectory files, an inclusive search is made. That is, all normal file entries plus all entries matching any specified attributes are returned. Normal files are files without any mode bits set. They may be read from or written to.
ulrc (APIRET) - returns
DosFindFirst returns one of the following values: