Функция FindFirstFile

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

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

Синтаксис

HANDLE FindFirstFile(
  LPCTSTR lpFileName,               // имя файла
  LPWIN32_FIND_DATA lpFindFileData  // буфер данных
);

Параметры

lpFileName

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

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

Windows 95/98/Me: Эта символьная строка не должна выходить за пределы количества  символов значения MAX_PATH.

lpFindFileData

[out] Указатель на структуру WIN32_FIND_DATA, которая получает информацию о найденном файле или вложенном каталоге.

Возвращаемые значения

Если функция завершается успешно, возвращаемое значение - дескриптор поиска, используемый в последующем вызове функции FindNextFile или FindClose.

Если функция завершается ошибкой, возвращаемое значение - INVALID_HANDLE_VALUE. Чтобы получить дополнительные данные об ошибке, вызовите GetLastError.

Замечания

Функция FindFirstFile открывает дескриптор  поиска  и возвращает информацию о первом файле, имя которого соответствует указанному образцу. Она ищет и длинные и короткие имена файла. После того, как дескриптор поиска был установлен,  функция FindNextFile используется, чтобы искать другие файлы, которые соответствуют некоторому шаблону. Когда дескриптор поиска - больше не нужен, закройте  его, используя функцию FindClose.

В редких случаях, информация об атрибутах файла файловой системы NTFS  может быть не текущей, когда Вы вызываете эту функцию. Чтобы получить текущие атрибуты файла NTFS, вызовите функцию GetFileInformationByHandle.

Эта функция ищет файлы только по имени; она не может использоваться для поиска на основе атрибута.

Вы не можете использовать корневые каталоги как вводимую строку в параметре lpFileName  для FindFirstFile, с или без заключительного обратного слэша (\). Чтобы проверить файлы в корневом каталоге, используйте что то подобное "C:\* " и пройдитесь по всему каталогу при помощи функции FindNextFile. Чтобы получить атрибуты корневого каталога, используйте функцию GetFileAttributes. Присоединенная спереди символьная строка "\\?\ " не дает доступ к корневому каталогу.

Точно так же в  сетевом ресурсе Вы можете использовать для параметра lpFileName форму "\\server\service\*", но нельзя использовать lpFileName, который указывает на ресурс непосредственно, типа "\\server\service".

Чтобы исследовать какой-либо каталог, а не корневой каталог, используйте соответствующий путь к этому каталогу без завершающего обратного слэша (\). Например, аргумент "C:\windows" возвратит информацию о каталоге "C:\windows", а не о каком-либо каталоге или файле в "C:\windows". Попытка открыть поиск с конечным обратным слэшем (\) будет всегда завершаться ошибкой.

Отдавайте себе отчет в том, что кто - то может создать или удалить этот файл в промежутке времени, когда Вы сделали запрос о результатах поиска и когда получили ответную информацию. Поэтому, если Вы надумали создать файл, лучше использовать функцию CreateFile с CREATE_NEW (сбой, если файл существует) или OPEN_EXISTING (сбой, если файл не существует).

Код примера

Нижеследующий код показывает минимальное использование функции 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 = FindFirstFile(argv[1], &FindFileData);

  if (hFind == INVALID_HANDLE_VALUE) 
  {
    printf ("Invalid File Handle. GetLastError reports %d\n",
             GetLastError ());
    return (0);
  } 
   else 
    {
    printf ("The first file found is %s\n", FindFileData.cFileName);
    FindClose(hFind);
    return (1);
    }
 }

Другой пример, см. в статье Список файлов в каталоге.

Смотри также 

Обзор Управление файлами, Функции, используемые в управлении файлами, FindClose, FindFirstFileEx, FindNextFile, GetFileAttributes, SetFileAttributes, WIN32_FIND_DATA 

Размещение и совместимость FindFirstFile
К

Windows XP

Да 
л

Windows 2000 Professional

Да
и

Windows NT Workstation

Да
е

Windows Me

Да
н

Windows 98

Да
т

Windows 95

Да
 
С

Windows Server 2003

Да
е Windows 2000 Server Да
р Windows NT Server Да
в    
е    
р    

Используемая библиотека

Kernel32.lib
Используемая DLL -
 Заголовочный файл  

- объявлено в

Winbase.h
 - включено в

Windows.h
 Unicode

Реализуется как версии Unicode и  ANSI для Windows 2000/XP. А также поддерживается программой Microsoft Layer for Unicode.
 Замечания по платформе

Не имеется

 

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

Hosted by uCoz