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

Статья
11/20/2024

[Корпорация Майкрософт настоятельно рекомендует разработчикам использовать альтернативные средства для достижения потребностей вашего приложения. Многие сценарии, для которые 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_OPSFileExSearchNameMatch и выполнять собственную фильтрацию.

После установки дескриптора поиска используйте его в функции 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 CreateFile с CREATE_NEW (которая завершается ошибкой, если файл существует) или OPEN_EXISTING (который завершается ошибкой, если файл не существует).

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

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

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

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

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

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows Vista [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2008 [только классические приложения]
целевая платформа	Виндоус
заголовка	winbase.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll