функция обратного вызова 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 заменяет его большим. Затем драйвер минифильтра сохраняет сведения о имени файла в буфер имен и возвращается.