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

Статья
11/20/2024

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

Основная версия этой функции см. в разделе 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_OPSFileExSearchNameMatch и выполнять собственную фильтрацию.

После установки дескриптора поиска используйте его в функции 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 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 (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]
целевая платформа	Виндоус
заголовка	fileapi.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll