PFLT_GENERATE_FILE_NAME回调函数（fltkernel.h）

项目
02/06/2025

为筛选器管理器的名称缓存提供文件名的微型筛选器驱动程序可以将类型 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 的例程的地址存储在 GenerateFileNameCallbackFLT_REGISTRATION 结构的成员中，微型筛选器驱动程序作为参数传递给 FltRegisterFilter。

筛选器管理器调用此回调例程，以允许微型筛选器驱动程序在微型筛选器实例堆栈中截获其上方的其他微型筛选器驱动程序的文件名请求。使用此回调例程和 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 将其替换为更大的缓冲区。然后，微型筛选器驱动程序将文件名信息存储在名称缓冲区中并返回。