Функция FindFirstFileEx


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

Синтаксис

HANDLE FindFirstFileEx(
  LPCTSTR lpFileName,              // имя файла
  FINDEX_INFO_LEVELS fInfoLevelId, // информационный уровень
  LPVOID lpFindFileData,           // буфер для информации
  FINDEX_SEARCH_OPS fSearchOp,     // тип фильтрации
  LPVOID lpSearchFilter,           // критерии поиска
  DWORD dwAdditionalFlags          // зарезервировано
);

Параметры

lpFileName
[in] Указатель на символьную строку с нулем в конце, определяющую правильный каталог или путь и имя файла, которое может содержать символы подстановки (* и ?). Если  символьная строка заканчивается  символом подстановки, точкой или именем каталога, пользователь должен иметь доступ к корневому каталогу и всем вложенным в него каталогам на пути.

Windows NT/2000/XP: В версии ANSI этой функции, имя ограничено количеством символов значения MAX_PATH. Чтобы выйти за пределы этого ограничения, до длины 32 767 символов, вызовите Unicode версию этой функции и присоедините спереди пути "\\?\". Подробную информацию см. в статье Именование файлов.

fInfoLevelId
[in] Информационный уровень возвращенных данных. Этот параметр - одно из перечисляемых значений FINDEX_INFO_LEVELS.
lpFindFileData
[out] Указатель на буфер, который получает данные о файле. Тип указателя определяется уровнем информации, заданным в параметре fInfoLevelId.

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_OPSFindFirstFileFindNextFileFindClose, 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.

 Замечания по платформе

Не имеется

 

Назад в оглавление
На главную страницу
На оглавление справки

Hosted by uCoz