функция обратного вызова PFLT_GENERATE_FILE_NAME (fltkernel.h)

Статья
08/07/2023

Драйвер минифильтра, предоставляющий имена файлов для кэша имен диспетчера фильтров, может зарегистрировать подпрограмму типа PFLT_GENERATE_FILE_NAME в качестве подпрограммы GenerateFileNameCallback драйвера минифильтра.

Синтаксис

PFLT_GENERATE_FILE_NAME PfltGenerateFileName;

NTSTATUS PfltGenerateFileName(
  [in]           PFLT_INSTANCE Instance,
  [in]           PFILE_OBJECT FileObject,
  [in, optional] PFLT_CALLBACK_DATA CallbackData,
  [in]           FLT_FILE_NAME_OPTIONS NameOptions,
  [out]          PBOOLEAN CacheFileNameInformation,
  [out]          PFLT_NAME_CONTROL FileName
)
{...}

Параметры

[in] Instance

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

[in] FileObject

Указатель на объект файла, имя которого запрашивается.

[in, optional] CallbackData

Указатель на структуру данных обратного вызова для операции, во время которой запрашивается это имя. Этот параметр имеет значение NULL , если метод FltGetFileNameInformationUnsafe вызывается для получения имени файла.

[in] NameOptions

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

[out] CacheFileNameInformation

Указатель на логическое значение, указывающее, можно ли кэшировать это имя. Установите значение TRUE в выходных данных, если имя может быть кэшировано; В противном случае задайте значение FALSE .

[out] FileName

Указатель на выделенную диспетчером фильтра структуру FLT_NAME_CONTROL для получения имени файла в выходных данных.

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

Эта подпрограмма обратного вызова возвращает STATUS_SUCCESS или соответствующее значение NTSTATUS.

Чтобы зарегистрировать эту подпрограмму обратного вызова, драйвер минифильтра сохраняет адрес подпрограммы типа PFLT_GENERATE_FILE_NAME в элементе GenerateFileNameCallbackструктуры FLT_REGISTRATION , которую драйвер минифильтра передает в качестве параметра в FltRegisterFilter.

Диспетчер фильтров вызывает эту подпрограмму обратного вызова, чтобы позволить драйверу минифильтра перехватывать запросы имен файлов от других драйверов минифильтра над ним в стеке экземпляров драйвера минифильтра. Используя эту процедуру обратного вызова и процедуру обратного вызова PFLT_NORMALIZE_NAME_COMPONENT , драйвер минифильтра может предоставить собственные сведения об имени файла.

Чтобы определить, какой формат имени файла запрашивается, вызовите FltGetFileNameFormat в параметре NameOptions .

До Windows 8 эта подпрограмма обратного вызова вызывалась только для открытых имен файлов и коротких имен файлов. Когда диспетчер фильтров получает запрос на получение нормализованного имени файла, он вызывает эту процедуру обратного вызова для запроса имени открытого файла. Затем он вызывает обратный вызов PFLT_NORMALIZE_NAME_COMPONENT драйвера минифильтра, чтобы нормализовать каждый компонент в имени файла.

Начиная с Windows 8 эта подпрограмма обратного вызова также вызывается для нормализованных имен. Когда диспетчер фильтров получает запрос на получение нормализованного имени файла, он вызывает эту подпрограмму обратного вызова с FLT_FILE_NAME_NORMALIZED, указанным в параметре NameOptions . Если минифильтр возвращает STATUS_SUCCESS из этого обратного вызова, обратный вызов PFLT_NORMALIZE_NAME_COMPONENT минифильтра не будет вызываться. Если минифильтр возвращает код сбоя (например, STATUS_NOT_SUPPORTED), диспетчер фильтров снова вызовет эту процедуру обратного вызова, запрашивая имя открытого файла. Затем диспетчер фильтров вызовет обратный вызов PFLT_NORMALIZE_NAME_COMPONENT драйвера минифильтра, чтобы нормализовать каждый компонент в имени файла.

При вызове этой подпрограммы обратного вызова драйвер минифильтра создает собственные сведения об имени файла на основе сведений об имени файла в файловой системе. Чтобы получить сведения об имени файла файловой системы, вызовите методы FltGetFileNameInformation, FltGetFileNameInformationUnsafe или FltGetDestinationFileNameInformation.

Для открытых имен файлов созданные сведения об имени файла должны включать сведения о томе. Для удаленного файла он также должен содержать сведения о совместном доступе.

Ниже приведен пример имени открытого файла для удаленного файла.

\Device\LanManRedirector\MyServer\MyShare\Docume~1\MyUser\My Documents\TestRe~1.txt:stream1

Дополнительные сведения о форматах имен файлов см. в справочных записях для FLT_FILE_NAME_INFORMATION и FltParseFileNameInformation.

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

Требования

Требование	Значение
Целевая платформа	Персональный компьютер
Верхняя часть	fltkernel.h (включая Fltkernel.h)
IRQL	PASSIVE_LEVEL