FindFirstFileEx Function

This topic describes the FindFirstFileEx function, which is part of the Windows API.

Syntax

HANDLE FindFirstFileEx(
  LPCWSTR            lpFileName,
  FINDEX_INFO_LEVELS fInfoLevelId,
  LPVOID             lpFindFileData,
  FINDEX_SEARCH_OPS  SearchOp,
  LPVOID             lpSearchFilter,
  DWORD              dwAdditionalFlags
);
        

Parameters

Parameter	Type	Description
lpFileName	LPCWSTR	A null-terminated string that specifies the path and file name pattern. The pattern can include wildcard characters. For example, you can specify "C:\\temp\\* .txt" to find all text files in the C:\temp directory.
fInfoLevelId	FINDEX_INFO_LEVELS	The type of information to be returned in the buffer pointed to by lpFindFileData. This parameter can be one of the following values from the FINDEX_INFO_LEVELS enumeration: FindExInfoStandard: Returns standard file information. FindExInfoBasic: Returns basic file information. FindExInfoMaxInfoLevel: Should not be used.
lpFindFileData	LPVOID	A pointer to a buffer that receives the file information. The type of information is determined by the fInfoLevelId parameter. If fInfoLevelId is FindExInfoStandard, lpFindFileData points to a WIN32_FIND_DATA structure. If fInfoLevelId is FindExInfoBasic, lpFindFileData points to a WIN32_FIND_DATAA or WIN32_FIND_DATAW structure (depending on the ANSI/Unicode version of the function).
SearchOp	FINDEX_SEARCH_OPS	The type of operation to perform. This parameter can be one of the following values from the FINDEX_SEARCH_OPS enumeration: FindExSearchNameOp: Searches for files with names matching the pattern. FindExSearchOp_MAX_SEARCH_OPS: Should not be used.
lpSearchFilter	LPVOID	A pointer to a structure that contains a file system specific search filter. For most applications, this parameter should be NULL.
dwAdditionalFlags	DWORD	Flags that specify how to perform the search. This parameter can be zero or one of the following values: FIND_FIRST_EX_CASE_SENSITIVE: The search is case-sensitive. FIND_FIRST_EX_ROOT_DIR: The search is for the root directory.

Return Value

If the function succeeds, the return value is a search handle identifying a changed file or directory. This handle is used by the FindNextFileEx and FindClose functions.

If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

Remarks

The FindFirstFileEx function opens a handle to the first file that matches the specified pattern in a directory. The handle is an opaque, memory-based value that is used by subsequent calls to FindNextFileEx to retrieve subsequent matches.

The lpFindFileData buffer can be either a WIN32_FIND_DATA structure (if fInfoLevelId is FindExInfoStandard) or a WIN32_FIND_DATAA/WIN32_FIND_DATAW structure (if fInfoLevelId is FindExInfoBasic).

The SearchOp parameter is currently limited to FindExSearchNameOp for general file searching.

The lpSearchFilter parameter is typically set to NULL unless you are performing advanced, file-system-specific searches.

The dwAdditionalFlags parameter allows for case-sensitive searches and searching for the root directory.

After you have finished using the search handle, you must close it using the FindClose function.

Examples

The following example demonstrates how to use FindFirstFileEx to find all text files in the current directory.

#include <windows.h>
#include <iostream>

int main() {
    WIN32_FIND_DATA findFileData;
    HANDLE hFind = INVALID_HANDLE_VALUE;

    // Find the first .txt file in the current directory.
    hFind = FindFirstFileEx(
        L"*.txt",                // file name pattern
        FindExInfoStandard,      // information level
        &findFileData,           // data buffer
        FindExSearchNameOp,      // search operation
        NULL,                    // search filter
        0                        // additional flags
    );

    if (hFind == INVALID_HANDLE_VALUE) {
        std::cerr << "Error finding files: " << GetLastError() << std::endl;
        return 1;
    }

    // Loop through all files found.
    do {
        std::wcout << findFileData.cFileName << std::endl;
    } while (FindNextFileEx(hFind, FindExInfoStandard, &findFileData, FindExSearchNameOp, NULL, 0));

    // Check for errors after the loop.
    if (GetLastError() != ERROR_NO_MORE_FILES) {
        std::cerr << "Error during file search: " << GetLastError() << std::endl;
    }

    // Close the search handle.
    FindClose(hFind);

    return 0;
}
        

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	fileapi.h (include windows.h)
Library	Use Kernel32.lib
DLL	Kernel32.dll

See Also

• FindNextFileEx
• FindClose
• WIN32_FIND_DATA
• File Management Functions