Функция FindFirstFileExA (fileapi.h)
Выполняет поиск в каталоге файла или подкаталога с именем и атрибутами, соответствующими указанным.
Самую простую версию этой функции см. в разделе 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
Задает дополнительные флаги, управляющие поиском.
Возвращаемое значение
Если функция выполняется успешно, возвращаемое значение представляет собой дескриптор поиска, используемый при последующем вызове FindNextFile или FindClose, а параметр lpFindFileData содержит сведения о первом найденном файле или каталоге.
Если функции не удается найти файлы из строки поиска в параметре lpFileName , возвращаемое значение будет INVALID_HANDLE_VALUE а содержимое lpFindFileData не определено. Чтобы получить расширенные сведения об ошибке, вызовите функцию GetLastError .
Комментарии
Функция FindFirstFileEx открывает дескриптор поиска и возвращает сведения о первом файле, найденном файловой системой, с именем, соответствующим указанному шаблону. Это может быть или не первый файл или каталог, который отображается в приложении со списком каталогов (например, команда dir), если задан тот же шаблон строки имени файла. Это связано с тем , что FindFirstFileEx не выполняет сортировку результатов поиска. Дополнительные сведения см. в разделе FindNextFile.
В следующем списке указаны некоторые другие характеристики поиска:
- Поиск выполняется исключительно по имени файла, а не по каким-либо атрибутам, таким как дата или тип файла.
- Поиск включает длинные и короткие имена файлов.
- Попытка открыть поиск с конечной обратной косой чертой всегда завершается неудачей.
- Передача недопустимой строки, NULL или пустой строки для параметра lpFileName не является допустимым использованием этой функции. В этом случае результаты не определены.
После установки дескриптора поиска используйте его в функции 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 |