PFLT_NORMALIZE_NAME_COMPONENT_EX回调函数 (fltkernel.h)

项目
02/29/2024

为筛选器管理器的名称缓存提供文件名的微筛选器驱动程序可以将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 操作的目标。有关详细信息，请参阅下面的 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 回调例程与 PFLT_NORMALIZE_NAME_COMPONENT ) 类型的 NormalizeNameComponentExCallback 回调例程 (的主要区别在于 NormalizeNameComponentExCallback 回调例程支持附加的 FileObject 参数。微筛选器驱动程序可以使用 FileObject) (文件对象，通过调用 IoGetTransactionParameterBlock 例程检索文件/目录正在参与的操作的TXN_PARAMETER_BLOCK结构。微筛选器驱动程序可以使用TXN_PARAMETER_BLOCK结构在此文件对象参与的事务上下文中发出自己的创建请求。

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

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

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