PFLT_GENERATE_FILE_NAME回调函数 (fltkernel.h)

项目
02/26/2024

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

指向正在请求此名称的操作的回调数据结构的指针。调用 FltGetFileNameInformationUnsafe 以检索文件名时，此参数为 NULL。

[in] NameOptions

FLT_FILE_NAME_OPTIONS 值，该值指定此文件名信息查询的名称格式、查询方法和标志。

[out] CacheFileNameInformation

指向布尔值的指针，指定是否可以缓存此名称。如果名称可以缓存，则输出时设置为 TRUE ;否则，设置为 FALSE 。

[out] FileName

指向筛选器管理器分配的FLT_NAME_CONTROL 结构的指针，用于接收输出时的文件名称。

返回值

此回调例程返回STATUS_SUCCESS或相应的 NTSTATUS 值。

注解

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

筛选器管理器调用此回调例程，以允许微筛选器驱动程序在微筛选器驱动程序实例堆栈中截获其上方的其他微筛选器驱动程序的文件名请求。使用此回调例程和 PFLT_NORMALIZE_NAME_COMPONENT 回调例程，微筛选器驱动程序可以提供其自己的文件名信息。

若要确定请求的文件名格式，请在 NameOptions 参数上调用 FltGetFileNameFormat。

在Windows 8之前，仅对打开的文件名和短文件名调用此回调例程。当筛选器管理器收到规范化文件名的请求时，它会调用此回调例程来请求打开的文件名。然后，它会调用微筛选器驱动程序的 PFLT_NORMALIZE_NAME_COMPONENT 回调，以规范化文件名中的每个组件。

从Windows 8开始，规范化名称也调用此回调例程。当筛选器管理器收到对规范化文件名的请求时，它会使用 NameOptions 参数中指定的FLT_FILE_NAME_NORMALIZED调用此回调例程。如果微筛选器从此回调返回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，以检查 FileName 参数指向的FLT_NAME_CONTROL结构是否包含足以保存生成的文件名的名称缓冲区。如果名称缓冲区太小， FltCheckAndGrowNameControl 会将它替换为更大的名称缓冲区。然后，微筛选器驱动程序将文件名信息存储在名称缓冲区中并返回。