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

Статья
06/02/2023

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

Самую простую версию этой функции см. в разделе FindFirstFile.

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

Синтаксис

HANDLE FindFirstFileExA(
  [in]  LPCSTR             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 767 символов в ширину, добавьте к пути "\\?\". Дополнительные сведения см. в статье Именование файлов, путей и пространств имен.

Совет

Начиная с Windows 10 версии 1607, вы можете согласиться на удаление ограничения 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	Да
SMB 3.0 Transparent Failover (TFO)	Да
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 или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования


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