FindFirstFileEx

The FindFirstFileEx function searches a directory for a file whose name and attributes match those specified in the function call.

HANDLE FindFirstFileEx(
  LPCTSTR lpFileName,              // file name
  FINDEX_INFO_LEVELS fInfoLevelId, // information level
  LPVOID lpFindFileData,           // information buffer
  FINDEX_SEARCH_OPS fSearchOp,     // filtering type
  LPVOID lpSearchFilter,           // search criteria
  DWORD dwAdditionalFlags          // additional search control
);

Parameters

lpFileName

[in] Pointer to a null-terminated string that specifies a valid directory or path and file name, which can contain wildcard characters (* and ?).

In the ANSI version of this function, the name is limited to MAX_PATH characters. To extend this limit to nearly 32,000 wide characters, call the Unicode version of the function and prepend "\\?\" to the path. For more information, see File Name Conventions.

fInfoLevelId

[in] Specifies a FINDEX_INFO_LEVELS enumeration type that gives the information level of the returned data.

lpFindFileData

[out] Pointer to the buffer that receives the file data. The pointer type is determined by the level of information specified in the fInfoLevelId parameter.

fSearchOp

[in] Specifies a FINDEX_SEARCH_OPS enumeration type that gives the type of filtering to perform beyond wildcard matching.

lpSearchFilter

[in] If the specified fSearchOp needs structured search information, lpSearchFilter points to the search criteria. At this time, none of the supported fSearchOp values require extended search information. Therefore, this pointer must be NULL.

dwAdditionalFlags

[in] Specifies additional optionsfor controlling the search. You can use FIND_FIRST_EX_CASE_SENSITIVE for case-sensitive searches. The default search is case insensitive. At this time, no other flags are defined.

Return Values

If the function succeeds, the return value is a search handle that can be used in a subsequent call to the FindNextFile or FindClose functions.

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

Remarks

The FindFirstFileEx function is provided to open a search handle and return information about the first file whose name matches the specified pattern and attributes.

If the underlying file system does not support the specified type of filtering, other than directory filtering, FindFirstFileEx fails with the error ERROR_NOT_SUPPORTED. The application has to use FINDEX_SEARCH_OPS type FileExSearchNameMatch and perform its own filtering.

After the search handle has been established, use it in the FindNextFile function to search for other files that match the same pattern with the same filtering being performed. When the search handle is no longer needed, it should be closed using the FindClose function.

You cannot use root directories as the lpFileName input string for FindFirstFileEx, with or without a trailing backslash. To examine files in a root directory, use something like "C:\*" and step through the directory with FindNextFile. To get the attributes of a root directory, use GetFileAttributes. Prepending the string "\\?\" does not allow access to the root directory.

Similarly, on network shares, you can use an lpFileName of the form "\\server\service\*" but you cannot use an lpFileName that points to the share itself, such as "\\server\service".

To examine any directory other than a root directory, use an appropriate path to that directory, with no trailing backslash. For example, an argument of "C:\windows" will return information about the directory "C:\windows", not about any directory or file in "C:\windows". An attempt to open a search with a trailing backslash will always fail.

The call

FindFirstFileEx( lpFileName, 
                 FindExInfoStandard, 
                 lpFindData, 
                 FindExSearchNameMatch, 
                 NULL, 
                 0 );

is equivalent to the call

FindFirstFile( lpFileName, lpFindData);

The following code shows a minimal use of FindFirstFileEx. This program is the equivalent of the example shown in FindFirstFile.

#define _WIN32_WINNT 0x0400

#include "windows.h"

int
main(int argc, char *argv[])
{
  WIN32_FIND_DATA FindFileData;
  HANDLE hFind;

  printf ("Target file is %s.\n", argv[1]);

  hFind = FindFirstFileEx(argv[1], FindExInfoStandard, &FindFileData,
                 FindExSearchNameMatch, NULL, 0 );

  if (hFind == INVALID_HANDLE_VALUE) {
    printf ("Invalid File Handle. Get Last Error reports %d\n", GetLastError ());
  } else {
    printf ("The first file found is %s\n", FindFileData.cFileName);
    FindClose(hFind);
  }

  return (0);
}

Requirements

  Windows NT/2000: Requires Windows NT 4.0 or later.
  Windows 95/98: Unsupported.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Kernel32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

File I/O Overview, File I/O Functions, FINDEX_INFO_LEVELS, FINDEX_SEARCH_OPS, FindFirstFile, FindNextFile, FindClose, GetFileAttributes