Функция FindFirstFileExW (fileapi.h)

Статья
06/02/2023

Выполняет поиск в каталоге файла или подкаталога с именем и атрибутами, соответствующими указанным.

Наиболее базовая версия этой функции см. в разделе FindFirstFile.

Чтобы выполнить эту операцию как транзакцию, используйте функцию FindFirstFileTransacted .

Синтаксис

HANDLE FindFirstFileExW(
  [in]  LPCWSTR            lpFileName,
  [in]  FINDEX_INFO_LEVELS fInfoLevelId,
  [out] LPVOID             lpFindFileData,
  [in]  FINDEX_SEARCH_OPS  fSearchOp,
        LPVOID             lpSearchFilter,
  [in]  DWORD              dwAdditionalFlags
);

Параметры

[in] lpFileName

Каталог или путь, а также имя файла. Имя файла может содержать подстановочные знаки, например звездочку (*) или вопросительный знак (?).

Этот параметр не должен иметь значение NULL, недопустимую строку (например, пустую строку или строку, в которую отсутствует завершающий символ NULL) или заканчиваться обратной косой чертой (\).

Если строка заканчивается подстановочным знаком, точкой или именем каталога, пользователь должен иметь доступ к корню и всем подкаталогам по пути.

В этой функции имя ограничено MAX_PATH символами. Чтобы расширить это ограничение примерно до 32 000 символов в ширину, вызовите версию функции в Юникоде (FindFirstFileExW) и добавьте "\?\" к пути. Дополнительные сведения см. в разделе Именование файла.

Совет Начиная с Windows 10 версии 1607 для версии юникода этой функции (FindFirstFileExW) можно согласиться на удаление ограничения символов MAX_PATH без добавления "\?\". Дополнительные сведения см. в разделе "Максимальное ограничение пути" статьи Именование файлов, путей и пространств имен .

[in] fInfoLevelId

Уровень сведений возвращаемых данных.

Этот параметр является одним из FINDEX_INFO_LEVELS значений перечисления.

[out] lpFindFileData

Указатель на буфер, получающий данные файла.

Тип указателя определяется уровнем сведений, указанным в параметре fInfoLevelId .

[in] fSearchOp

Тип фильтрации для выполнения, отличающийся от сопоставления с подстановочными знаками.

Этот параметр является одним из FINDEX_SEARCH_OPS значений перечисления.

lpSearchFilter

Указатель на критерии поиска, если указанному fSearchOp требуются структурированные сведения о поиске.

В настоящее время ни одно из поддерживаемых значений fSearchOp не требует расширенных сведений поиска. Поэтому этот указатель должен иметь значение NULL.

[in] dwAdditionalFlags

Задает дополнительные флаги, управляющие поиском.

Значение	Значение
FIND_FIRST_EX_CASE_SENSITIVE 1	При поиске учитывается регистр.
FIND_FIRST_EX_LARGE_FETCH 2	Использует больший буфер для запросов каталогов, что может повысить производительность операции поиска. Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Это значение не поддерживается до Windows Server 2008 R2 и Windows 7.
FIND_FIRST_EX_ON_DISK_ENTRIES_ONLY 4	Ограничивает результаты файлами, которые физически находятся на диске. Этот флаг подходит только при наличии фильтра виртуализации файлов.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение представляет собой дескриптор поиска, используемый при последующем вызове FindNextFile или FindClose, а параметр lpFindFileData содержит сведения о первом найденном файле или каталоге.

Если функции не удается найти файлы из строки поиска в параметре lpFileName , возвращаемое значение будет INVALID_HANDLE_VALUE , а содержимое lpFindFileData является неопределенным. Чтобы получить расширенные сведения об ошибке, вызовите функцию GetLastError .

Функция FindFirstFileEx открывает дескриптор поиска и возвращает сведения о первом файле, найденном файловой системой, с именем, соответствующим указанному шаблону. Это может быть или не может быть первым файлом или каталогом, который отображается в приложении со списком каталогов (например, в команде dir) при использовании одного и того же шаблона строки имени файла. Это связано с тем, что FindFirstFileEx не сортирует результаты поиска. Дополнительные сведения см. в разделе FindNextFile.

В следующем списке указаны некоторые другие характеристики поиска.

Поиск выполняется строго по имени файла, а не по каким-либо атрибутам, таким как дата или тип файла.
Поиск включает длинные и короткие имена файлов.
Попытка открыть поиск с обратной косой чертой в конце всегда завершается неудачей.
Передача недопустимой строки, NULL или пустой строки для параметра lpFileName не является допустимым использованием этой функции. В этом случае результаты не определены.

Примечание В редких случаях или в сильно загруженной системе сведения об атрибутах файлов в файловых системах NTFS могут не быть актуальными на момент вызова этой функции. Чтобы убедиться в получении текущих атрибутов файловой системы NTFS, вызовите функцию GetFileInformationByHandle .

Если базовая файловая система не поддерживает указанный тип фильтрации, кроме фильтрации каталогов, FindFirstFileEx завершается ошибкой ERROR_NOT_SUPPORTED. Приложение должно использовать FINDEX_SEARCH_OPS тип FileExSearchNameMatch и выполнять собственную фильтрацию.

После установки дескриптора поиска используйте его в функции FindNextFile для поиска других файлов, соответствующих тому же шаблону, с той же фильтрацией, которая выполняется. Если дескриптор поиска не требуется, его следует закрыть с помощью функции FindClose .

Как упоминалось ранее, вы не можете использовать обратную косую черту (\) во входной строке lpFileName для FindFirstFileEx, поэтому поиск в корневых каталогах может оказаться неясным. Если вы хотите просмотреть файлы или получить атрибуты корневого каталога, применяются следующие параметры:

Чтобы изучить файлы в корневом каталоге, можно использовать "C:\*" и выполнить пошаговое руководство по каталогу с помощью findNextFile.
Чтобы получить атрибуты корневого каталога, используйте функцию GetFileAttributes .

Примечание При добавлении строки "\?\" доступ к корневому каталогу не разрешен.

В общих сетевых ресурсах можно использовать lpFileName в следующем виде: "\\server\service\*". Однако нельзя использовать lpFileName , указывающее на сам общий ресурс; Например, "\\server\service" является недопустимым.

Чтобы проверить каталог, который не является корневым, используйте путь к нему без обратной косой черты. Например, аргумент "C:\Windows" возвращает сведения о каталоге "C:\Windows", а не о каталоге или файле в "C:\Windows". Чтобы проверить файлы и каталоги в "C:\Windows", используйте lpFileName "C:\Windows\*".

Следующий вызов:

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

Эквивалентен следующему вызову:

FindFirstFile( lpFileName, lpFindData );

Имейте в виду, что какой-либо другой поток или процесс может создать или удалить файл с таким именем между временем запроса к результату и временем действия с информацией. Если это потенциальная проблема для приложения, одним из возможных решений является использование функции CreateFile с CREATE_NEW (которая завершается сбоем, если файл существует) или OPEN_EXISTING (если файл не существует).

Если вы пишете 32-разрядное приложение для перечисления всех файлов в каталоге и приложение может быть запущено на 64-разрядном компьютере, необходимо вызвать Wow64DisableWow64FsRedirection перед вызовом FindFirstFileEx и Wow64RevertWow64FsRedirection после последнего вызова FindNextFile. Дополнительные сведения см. в разделе Перенаправитель файловой системы.

Если путь указывает на символьную ссылку, буфер WIN32_FIND_DATA содержит сведения о символьной ссылке, а не о целевом объекте.

В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.

Технология	Поддерживается
Протокол SMB 3.0	Да
Прозрачная отработка отказа (TFO) SMB 3.0	Да
SMB 3.0 с масштабируемыми общими папками (SO)	Да
Файловая система общего тома кластера (CSVFS)	Да
Восстанавливаемая файловая система (ReFS)	Да

Примеры

В следующем коде показано минимальное использование FindFirstFileEx. Эта программа эквивалентна примеру в разделе FindFirstFile .

#include <windows.h>
#include <tchar.h>
#include <stdio.h>

void _tmain(int argc, TCHAR *argv[])
{
   WIN32_FIND_DATA FindFileData;
   HANDLE hFind;

   if( argc != 2 )
   {
      _tprintf(TEXT("Usage: %s [target_file]\n"), argv[0]);
      return;
   }

   _tprintf (TEXT("Target file is %s\n"), argv[1]);
   hFind = FindFirstFileEx(argv[1], FindExInfoStandard, &FindFileData,
             FindExSearchNameMatch, NULL, 0);
   if (hFind == INVALID_HANDLE_VALUE) 
   {
      printf ("FindFirstFileEx failed (%d)\n", GetLastError());
      return;
   } 
   else 
   {
      _tprintf (TEXT("The first file found is %s\n"), 
                FindFileData.cFileName);
      FindClose(hFind);
   }
}

Примечание

Заголовок fileapi.h определяет FindFirstFileEx как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования


Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	fileapi.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll