Функция FindFirstFileEx ищет каталог файла или подкаталог, имя и атрибуты которого соответствуют тому, что определено в вызове функции.
Синтаксис
HANDLE FindFirstFileEx( LPCTSTR lpFileName, // имя файла FINDEX_INFO_LEVELS fInfoLevelId, // информационный уровень LPVOID lpFindFileData, // буфер для информации FINDEX_SEARCH_OPS fSearchOp, // тип фильтрации LPVOID lpSearchFilter, // критерии поиска DWORD dwAdditionalFlags // зарезервировано ); |
Параметры
Windows NT/2000/XP: В версии ANSI этой функции, имя ограничено количеством символов значения MAX_PATH. Чтобы выйти за пределы этого ограничения, до длины 32 767 символов, вызовите Unicode версию этой функции и присоедините спереди пути "\\?\". Подробную информацию см. в статье Именование файлов.
fSearchOp
[in] Тип фильтрации, который исполняется после проверки соответствия символу подстановки. Этот параметр - одно из перечисляемых значений FINDEX_SEARCH_OPS.lpSearchFilter
[in] Если заданному параметру fSearchOp требуется структурированная информация поиска, параметр lpSearchFilter указывает на критерии поиска. В это время, ни одно из поддерживаемых значений fSearchOp не требует дополнительной информации поиска. Поэтому, этот указатель должен быть ПУСТЫМ.dwAdditionalFlags
Зарезервированный для будущего использования. Этот параметр должен равняться нулю.
Возвращаемые значения
Если функция завершается успешно, возвращаемое значение - дескриптор поиска, используемый в последующем вызове функции FindNextFile или FindClose.
Если функция завершается ошибкой, возвращаемое значение - INVALID_HANDLE_VALUE. Чтобы получить дополнительные данные об ошибке, вызовите GetLastError.
Замечания
Функция FindFirstFileEx открывает дескриптор поиска и возвращает информацию о первом файле или поддиректории, имя которых соответствует указанному шаблону и атрибутам. Она ищет и длинные и короткие имена файла.
В редких случаях, информация об атрибутах файла файловой системы NTFS может быть не текущей во время, когда Вы вызываете эту функцию. Чтобы получить текущие атрибуты файла NTFS, вызовите функцию GetFileInformationByHandle.
Если основная файловая система не поддерживает указанный тип фильтрации, который отличается от фильтрации каталога, функция FindFirstFileEx завершается ошибкой со значением ERROR_NOT_SUPPORTED. Приложение должно использовать перечисляемый тип FINDEX_SEARCH_OPS функции FileExSearchNameMatch и выполнить свою собственную фильтрацию.
После того, как дескриптор поиска был установлен, используйте его в функции FindFirstFileEx, чтобы искать другие файлы, которые соответствуют одному и тому же шаблону с выполнением одной и той же фильтрации. Когда дескриптор поиска - больше не нужен, он должен быть закрыт, используя функцию FindClose.
Вы не можете использовать корневые каталоги как вводимую строку в параметре lpFileName для FindFirstFileEx, с или без заключительного обратного слэша (\). Чтобы проверить файлы в корневом каталоге, используйте что-то подобное "C:\* " и пройдитесь по всему каталогу при помощи функции FindNextFile. Чтобы получить атрибуты корневого каталога, используйте функцию GetFileAttributes. Присоединенная спереди символьная строка "\\?\ " не дает доступ к корневому каталогу.
Точно так же и в сетевом ресурсе Вы можете использовать для параметра lpFileName форму "\\server\service\*", но нельзя использовать lpFileName, который указывает на ресурс непосредственно, типа "\\server\service".
Чтобы исследовать какой-либо каталог, а не корневой каталог, используйте соответствующий путь к этому каталогу без завершающего обратного слэша (\). Например, аргумент "C:\windows" возвратит информацию о каталоге "C:\windows", а не о каком-либо каталоге или файле в "C:\windows". Попытка открыть поиск с конечным обратным слэшем (\) будет всегда завершаться ошибкой.
Вызов
FindFirstFileEx( lpFileName,
FindExInfoStandard,
lpFindData,
FindExSearchNameMatch,
NULL,
0 );
|
эквивалентен вызову
FindFirstFile( lpFileName, lpFindData); |
Чтобы компилировать приложение, которое использует эту функцию, определите макрос _WIN32_WINNT как 0x0400 или выше. Для получения дополнительной информации, см. статью Использование заголовочных файлов SDK.
Код примера
Нижеследующий код показывает минимальное использование FindFirstFileEx. Эта программа - эквивалент примера, показанного в FindFirstFile.
#define _WIN32_WINNT 0x0400
#include "windows.h"
#include <stdio.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 ());
return (0);
}
else
{
printf ("The first file found is %s\n", FindFileData.cFileName);
FindClose(hFind);
return (1);
}
}
|
Смотри также
Обзор Управление файлами, Функции, используемые в управлении файлами, FINDEX_INFO_LEVELS, FINDEX_SEARCH_OPS, FindFirstFile, FindNextFile, FindClose, GetFileAttributes
|
Размещение и совместимость FindFirstFileEx |
||
| К |
Windows XP |
Да |
| л |
Windows 2000 Professional |
Да |
| и |
Windows NT Workstation |
Да версии 4.0 |
| е |
Windows Me |
Нет |
| н |
Windows 98 |
Нет |
| т |
Windows 95 |
Нет |
| С |
Windows Server 2003 |
Да |
| е | Windows 2000 Server | Да |
| р | Windows NT Server | Да версии 4.0 |
| в | ||
| е | ||
| р | ||
|
Используемая библиотека |
Kernel32.lib |
|
| Используемая DLL | - | |
| Заголовочный файл | ||
|
- объявлено в |
Winbase.h |
|
| - включено в |
Windows.h |
|
| Unicode |
Реализуется как версии Unicode и ANSI. |
|
| Замечания по платформе |
Не имеется |
|