Функция FindFirstFileTransactedA (winbase.h)

Статья
06/02/2023

[Корпорация Майкрософт настоятельно рекомендует разработчикам использовать альтернативные средства для удовлетворения потребностей вашего приложения. Многие сценарии, для которые был разработан TxF, могут быть реализованы с помощью более простых и доступных методов. Кроме того, TxF может быть недоступен в будущих версиях Microsoft Windows. Дополнительные сведения и альтернативы TxF см. в статье Альтернативы использованию транзакционной NTFS.]

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

Эта функция является транзакцией функции FindFirstFileEx .

Наиболее базовая версия этой функции см. в разделе FindFirstFile.

Синтаксис

HANDLE FindFirstFileTransactedA(
  [in]  LPCSTR             lpFileName,
  [in]  FINDEX_INFO_LEVELS fInfoLevelId,
  [out] LPVOID             lpFindFileData,
  [in]  FINDEX_SEARCH_OPS  fSearchOp,
        LPVOID             lpSearchFilter,
  [in]  DWORD              dwAdditionalFlags,
  [in]  HANDLE             hTransaction
);

Параметры

[in] lpFileName

Каталог или путь, а также имя файла. Имя файла может содержать подстановочные знаки, например звездочку (*) или вопросительный знак (?).

Этот параметр не должен иметь значение NULL, недопустимую строку (например, пустую строку или строку, в которую отсутствует завершающий символ NULL) или заканчиваться обратной косой чертой (\).

Если строка заканчивается подстановочным знаком, точкой (.) или именем каталога, пользователь должен иметь доступ к корню и всем подкаталогам по пути.

По умолчанию имя ограничено MAX_PATH символами. Чтобы расширить это ограничение до 32 767 символов в ширину, добавьте к пути "\\?\". Дополнительные сведения см. в статье Именование файлов, путей и пространств имен.

Совет

Начиная с Windows 10 версии 1607, вы можете согласиться на удаление ограничения MAX_PATH без добавления "\\?\". Дополнительные сведения см. в разделе "Ограничение максимальной длины пути" статьи Именование файлов, путей и пространств имен .

Файл должен находиться на локальном компьютере; В противном случае функция завершается сбоем, а для последнего кода ошибки задано значение ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE.

[in] fInfoLevelId

Уровень сведений возвращаемых данных.

Этот параметр является одним из FINDEX_INFO_LEVELS значений перечисления.

[out] lpFindFileData

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

[in] fSearchOp

Тип фильтрации для выполнения, отличающийся от сопоставления с подстановочными знаками.

Этот параметр является одним из FINDEX_SEARCH_OPS значений перечисления.

lpSearchFilter

Указатель на критерии поиска, если указанному fSearchOp требуются структурированные сведения о поиске.

В настоящее время ни одно из поддерживаемых значений fSearchOp не требует расширенных сведений поиска. Поэтому этот указатель должен иметь значение NULL.

[in] dwAdditionalFlags

Задает дополнительные флаги, управляющие поиском.

Значение	Значение
FIND_FIRST_EX_CASE_SENSITIVE 1	При поиске учитывается регистр.

[in] hTransaction

Дескриптор транзакции. Этот дескриптор возвращается функцией CreateTransaction .

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

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

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

Функция FindFirstFileTransacted открывает дескриптор поиска и возвращает сведения о первом файле, найденном файловой системой, с именем, соответствующим указанному шаблону. Это может быть или не может быть первым файлом или каталогом, который отображается в приложении со списком каталогов (например, в команде dir) при использовании одного и того же шаблона строки имени файла. Это связано с тем, что FindFirstFileTransacted не сортирует результаты поиска. Дополнительные сведения см. в разделе FindNextFile.

В следующем списке указаны некоторые другие характеристики поиска.

Поиск выполняется строго по имени файла, а не по каким-либо атрибутам, таким как дата или тип файла.
Поиск включает длинные и короткие имена файлов.
Попытка открыть поиск с обратной косой чертой в конце всегда завершается неудачей.
Передача недопустимой строки, NULL или пустой строки для параметра lpFileName не является допустимым использованием этой функции. В этом случае результаты не определены.

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

Если базовая файловая система не поддерживает указанный тип фильтрации, кроме фильтрации каталогов, findFirstFileTransacted завершается ошибкой ERROR_NOT_SUPPORTED. Приложение должно использовать FINDEX_SEARCH_OPS тип FileExSearchNameMatch и выполнять собственную фильтрацию.

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

Как было сказано ранее, вы не можете использовать обратную косую черту (\) во входной строке lpFileName для FindFirstFileTransacted, поэтому поиск в корневых каталогах может оказаться неясным. Если вы хотите просмотреть файлы или получить атрибуты корневого каталога, применяются следующие параметры:

Чтобы изучить файлы в корневом каталоге, можно использовать "C:\*" и выполнить пошаговое руководство по каталогу с помощью findNextFile.
Чтобы получить атрибуты корневого каталога, используйте функцию GetFileAttributes .

Примечание При добавлении строки "\?\" доступ к корневому каталогу не разрешен.

В общих сетевых ресурсах можно использовать lpFileName в следующем виде: "\\server\service*". Однако нельзя использовать lpFileName , указывающее на сам общий ресурс; Например, "\\server\service" является недопустимым.

Чтобы проверить каталог, который не является корневым, используйте путь к нему без обратной косой черты. Например, аргумент "C:\Windows" возвращает сведения о каталоге "C:\Windows", а не о каталоге или файле в "C:\Windows". Чтобы проверить файлы и каталоги в "C:\Windows", используйте lpFileName "C:\Windows\*".

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

Если вы пишете 32-разрядное приложение для перечисления всех файлов в каталоге и приложение может быть запущено на 64-разрядном компьютере, следует вызвать Wow64DisableWow64FsRedirection перед вызовом FindFirstFileTransacted и Wow64RevertWow64FsRedirection после последнего вызова FindNextFile. Дополнительные сведения см. в разделе Перенаправитель файловой системы.

Если путь указывает на символьную ссылку, буфер WIN32_FIND_DATA содержит сведения о символьной ссылке, а не о целевом объекте.

В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.

Технология	Поддерживается
Протокол SMB 3.0	Нет
Прозрачная отработка отказа (TFO) SMB 3.0	Нет
SMB 3.0 с масштабируемыми общими папками (SO)	Нет
Файловая система общего тома кластера (CSVFS)	Нет
Восстанавливаемая файловая система (ReFS)	Нет

SMB 3.0 не поддерживает TxF.

Примечание

Заголовок winbase.h определяет FindFirstFileTransacted как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	winbase.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll