DosFindFirst Parameter - pfindbuf

pfindbuf (PVOID) - in/out

Result buffer.

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) :

On output, pfindbuf contains the FILEFINDBUF3 data structure without the last two fields: cchName and achName. This is used without EAs.

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.

For Level 2 File Information (ulInfoLevel == FIL_QUERYEASIZE) :
On output, pfindbuf contains the FILEFINDBUF4 data structure without the last two fields: cchName and achName. This is used with EAs.

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.

For Level 3 File Information (ulInfoLevel == FIL_QUERYEASFROMLIST) :
On input, pfindbuf contains an EAOP2 data structure. fpGEA2List contains a pointer to a GEA2 list, which defines the attribute names whose values are to be returned. Entries in the GEA2 list must be aligned on a doubleword boundary. Each oNextEntryOffset field must contain the number of bytes from the beginning of the current entry to the beginning of the next entry.

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, with the fpFEA2List pointer incorrect.

  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.

• A FILEFINDBUF3 data structure without the last two fields: cchName and achName.

• A FEA2LIST data structure contained in and related to the FILEFINDBUF3 returned.

• Length of the name string of the file object (cbName)

• Name of the file object matched by the input pattern (achName)
Even if there is not enough room to hold all of the requested information, as for return code ERROR_BUFFER_OVERFLOW, the cbList field of the FEA2LIST data structure is valid if there is at least enough space to hold it.

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.

---

[Back: DosFindFirst Parameter - flAttribute]
[Next: DosFindFirst Parameter - cbBuf]