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

Статья
08/07/2023

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

Синтаксис

PFLT_NORMALIZE_NAME_COMPONENT_EX PfltNormalizeNameComponentEx;

NTSTATUS PfltNormalizeNameComponentEx(
  [in]      PFLT_INSTANCE Instance,
  [in]      PFILE_OBJECT FileObject,
  [in]      PCUNICODE_STRING ParentDirectory,
  [in]      USHORT VolumeNameLength,
  [in]      PCUNICODE_STRING Component,
  [out]     PFILE_NAMES_INFORMATION ExpandComponentName,
  [in]      ULONG ExpandComponentNameLength,
  [in]      FLT_NORMALIZE_NAME_FLAGS Flags,
  [in, out] PVOID *NormalizationContext
)
{...}

Параметры

[in] Instance

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

[in] FileObject

Указатель на объект file для файла, имя которого запрашивается, или на файл, который является целевым объектом операции IRP_MJ_SET_INFORMATION , если установлен флаг FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME. Дополнительные сведения см. в описании параметра Flags ниже.

[in] ParentDirectory

Указатель на структуру UNICODE_STRING , содержащую имя родительского каталога для этого компонента имени.

[in] VolumeNameLength

Длина (в байтах) имени родительского каталога, хранящегося в структуре, на которую указывает параметр ParentDirectory .

[in] Component

Указатель на UNICODE_STRING структуру, содержащую развертываемый компонент имени.

[out] ExpandComponentName

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

[in] ExpandComponentNameLength

Длина (в байтах) буфера, на который указывает параметр ExpandComponentName .

[in] Flags

Флаги нормализации имен. FLTFL_NORMALIZE_NAME_CASE_SENSITIVE указывает, что имя для нормализации учитывает регистр. FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME указывает, что подпрограмма обратного вызова была вызвана для обслуживания вызова подпрограммы FltGetDestinationFileNameInformation . Если установлен флаг FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME, FileObject представляет файл или каталог, который является целевым объектом операции IRP_MJ_SET_INFORMATION. Если флаг FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME не задан, FileObject представляет файл или каталог, имя которого запрашивается.

[in, out] NormalizationContext

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

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

Эта подпрограмма обратного вызова возвращает STATUS_SUCCESS или соответствующее значение NTSTATUS. Если компонент имени, указанный в параметре Component , не существует в родительском каталоге, который указывает параметр ParentDirectory , эта подпрограмма обратного вызова должна возвращать STATUS_NO_SUCH_FILE. Если эта подпрограмма обратного вызова отправляет запрос IRP_MN_QUERY_DIRECTORY (FileNamesInformation) к родительскому каталогу, файловая система возвращает правильный код состояния. В этом случае обратный вызов может просто возвращать код состояния, возвращаемый файловой системой.

Основное различие между подпрограммой обратного вызова NormalizeNameComponentExCallback и подпрограммой обратного вызова NormalizeNameComponentCallback (типа PFLT_NORMALIZE_NAME_COMPONENT) заключается в том, что подпрограмма обратного вызова NormalizeNameComponentExCallback поддерживает дополнительный параметр FileObject . Файловый объект (FileObject) может использоваться драйвером минифильтра для получения структуры TXN_PARAMETER_BLOCK для операции, в которую участвует файл или каталог, путем вызова подпрограммы IoGetTransactionParameterBlock . Драйвер мини-фильтра может использовать структуру TXN_PARAMETER_BLOCK для выдачи собственных запросов на создание в контексте транзакции, в которую участвует этот файловый объект.

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

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

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

Требования

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