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

Статья
06/02/2023

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

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

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

Самую простую версию этой функции см. в разделе FindFirstFile.

Синтаксис

HANDLE FindFirstFileTransactedW(
  [in]  LPCWSTR            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) или заканчиваться обратной косой чертой (\).

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

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

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

Совет

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

[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	Нет
SMB 3.0 Transparent Failover (TFO)	Нет
SMB 3.0 с масштабируемыми общими папками (SO)	Нет
Файловая система общего тома кластера (CSVFS)	Нет
Восстанавливаемая файловая система (ReFS)	Нет

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

Примечание

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

Требования


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