FsRtlRemovePerStreamContext 函数 (ntifs.h)

项目
02/26/2024

FsRtlRemovePerStreamContext 从与文件流关联的每流上下文列表中删除每流上下文结构。

语法

PFSRTL_PER_STREAM_CONTEXT FsRtlRemovePerStreamContext(
  [in]           PFSRTL_ADVANCED_FCB_HEADER StreamContext,
  [in, optional] PVOID                      OwnerId,
  [in, optional] PVOID                      InstanceId
);

参数

[in] StreamContext

指向文件流的FSRTL_ADVANCED_FCB_HEADER结构的指针。若要从文件对象获取此指针，请使用 FsRtlGetPerStreamContextPointer 宏。

[in, optional] OwnerId

用于将上下文信息标识为属于特定筛选器驱动程序。

[in, optional] InstanceId

用于搜索每个流上下文的特定实例。如果未提供，则删除并返回筛选器驱动程序拥有的任何上下文。

如果未提供 OwnerId 和 InstanceId ，则将删除并返回任何关联的每流上下文。

返回值

FsRtlRemovePerStreamContext 返回指向已删除的每个流上下文的指针。如果未找到匹配项，或者文件系统不支持筛选器上下文， FsRtlRemovePerStreamContext 将返回 NULL。

注解

文件系统筛选器驱动程序调用 FsRtlRemovePerStreamContext ，以从与文件流关联的每流上下文列表中删除自己的每流上下文结构。

FsRtlRemovePerStreamContext 仅删除找到的第一个匹配的每流上下文结构。如果每个流有其他匹配的上下文，则筛选器驱动程序必须根据需要调用 FsRtlRemovePerStreamContext ，以将其全部删除。

仅当筛选器驱动程序需要放弃它与文件流关联的上下文信息时，才应使用此例程，而该流仍处于打开状态。例如，筛选器驱动程序在以下情况下可能会调用 FsRtlRemovePerStreamContext ：

当它收到来自用户模式应用程序的请求时，以停止记录特定卷上的 I/O 请求。
检测到文件或目录已重命名时。

当文件流关闭时，文件系统负责确保删除并释放与该流关联的所有每流上下文。为此，文件系统必须在文件控制块上调用 FsRtlTeardownPerStreamContexts ， (FCB) 或其他文件流的流上下文对象。 FsRtlTeardownPerStreamContexts 遍览 FilterContexts 列表，删除每个条目并调用其 FreeCallback 例程。

因此，文件系统筛选器驱动程序不应从IRP_MJ_CLOSE或IRP_MJ_PNP调度例程中调用 FsRtlRemovePerStreamContext 。这种调用不仅没有必要，而且还可能会干扰文件系统对 FsRtlTeardownPerStreamContexts 的调用。

文件系统筛选器驱动程序不应从每流上下文结构的 FreeCallback 例程中调用 FsRtlRemovePerStreamContext。这是因为基础文件系统在已从 FilterContexts 列表中删除上下文结构后调用 FreeCallback 例程。

若要初始化每流上下文结构，请使用 FsRtlInitPerStreamContext 宏。

若要将初始化的每流上下文结构与文件流相关联，请调用 FsRtlInsertPerStreamContext。

若要检索与文件流关联的每流上下文结构，请调用 FsRtlLookupPerStreamContext。

FsRtlRemovePerStreamContext 只能在支持筛选器上下文的文件系统上使用。

有关详细信息，请参阅在旧版文件系统筛选器驱动程序中跟踪 Per-Stream 上下文。

要求

要求	值
最低受支持的客户端	Windows 2000 SP4 更新汇总;Windowsxp
目标平台	通用
标头	ntifs.h (包括 Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL