PFLT_NORMALIZE_NAME_COMPONENT_EX回调函数（fltkernel.h）

项目
02/06/2025

为筛选器管理器的名称缓存提供文件名的微型筛选器驱动程序可以将类型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

指向要请求其名称的文件的文件对象的指针;如果设置了FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME标志，则指向 IRP_MJ_SET_INFORMATION作的目标文件。有关详细信息，请参阅下面的标志参数。

[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）通过调用 IoGetTransactionParameterBlock 例程来检索文件/目录参与的作的 TXN_PARAMETER_BLOCK 结构。微型筛选器驱动程序可以使用TXN_PARAMETER_BLOCK结构在此文件对象参与的事务上下文中发出自己的创建请求。

若要注册此回调例程，微型筛选器驱动程序会将类型PFLT_NORMALIZE_NAME_COMPONENT_EX的例程的地址存储在 NormalizeNameComponentExCallbackFLT_REGISTRATION 结构的成员中，微型筛选器驱动程序作为参数传递给 FltRegisterFilter。

筛选器管理器调用此回调例程，以查询小筛选器驱动程序的文件名路径中组件的规范化名称的微型筛选器驱动程序，这些组件的名称已修改。如果文件名路径包含多个此类组件，筛选器管理器可以在规范化路径中的所有组件的过程中多次调用此回调例程。微型筛选器驱动程序可以使用 NormalizationContext 参数将上下文信息传递给对此回调例程的后续调用。

如果微型筛选器驱动程序使用 NormalizationContext 参数，则它还应注册规范化上下文清理回调例程。有关详细信息，请参阅 PFLT_NORMALIZE_CONTEXT_CLEANUP的参考条目。