FSRTL_PER_STREAM_CONTEXT 结构 (ntifs.h)

项目
08/07/2023

FSRTL_PER_STREAM_CONTEXT 结构包含文件系统筛选器驱动程序维护的有关文件流的上下文信息。

语法

typedef struct _FSRTL_PER_STREAM_CONTEXT {
  LIST_ENTRY     Links;
  PVOID          OwnerId;
  PVOID          InstanceId;
  PFREE_FUNCTION FreeCallback;
} FSRTL_PER_STREAM_CONTEXT, *PFSRTL_PER_STREAM_CONTEXT;

成员

Links

此结构的链接位于与同一文件流关联的所有每流上下文结构的列表中。 FsRtlInsertPerStreamContext 将此成员插入文件流的所有按流上下文结构的列表中。若要从文件对象获取指向列表标题的指针，请使用 FsRtlGetPerStreamContextPointer 宏，并将结果强制转换为 PFSRTL_ADVANCED_FCB_HEADER 指针。列表指针是高级文件控制块中的 FilterContexts 成员， (文件流的 FCB) 标头结构。

OwnerId

指向筛选器驱动程序分配的变量的指针，该变量唯一标识每个流上下文结构的所有者。此变量的格式特定于筛选器驱动程序。筛选器编写器应选择既有意义又方便的值，例如驱动程序对象或设备对象的地址。筛选器驱动程序必须将此成员设置为非 NULL 值。

InstanceId

指向筛选器驱动程序分配的变量的指针，该变量可用于区分由同一筛选器驱动程序创建的按流上下文结构。此变量的格式特定于筛选器驱动程序。筛选器编写器应选择既有意义又方便的值，例如文件流的流上下文对象的地址。 (若要从文件对象获取此地址，请使用 FsRtlGetPerStreamContextPointer macro.)

此成员是可选的，可以为 NULL。

FreeCallback

指向释放按流上下文结构的回调例程的指针。此例程及其参数的定义如下：

VOID
(*PFREE_FUNCTION) (
     IN PVOID Buffer
     );

Buffer

指向要释放 的FSRTL_PER_STREAM_CONTEXT 结构的指针。

注解

文件系统筛选器驱动程序可以使用 FSRTL_PER_STREAM_CONTEXT 结构来维护文件流的上下文信息。此结构可以按原样使用，也可以嵌入到驱动程序定义的按流上下文结构中。

当文件系统删除文件流的流上下文对象时，它必须调用 FsRtlTeardownPerStreamContexts，后者又调用与文件流关联的所有每流上下文结构的 FreeCallback 例程。

注意FreeCallback 例程不能以递归方式调用文件系统或获取任何文件系统资源。此外，此例程必须假定已释放文件流的文件对象。

可以从分页池或非分页池分配 FSRTL_PER_STREAM_CONTEXT 结构。

FsRtlSupportsPerStreamContexts 宏确定文件系统是否支持给定文件流的按流上下文。

BOOLEAN FsRtlSupportsPerStreamContexts(
  [in] PFILE_OBJECT FileObject
);

参数

FileObject [in]

PFILE_OBJECT

指向文件流的文件对象的指针。

返回值

BOOLEAN

如果文件系统支持文件流的按流上下文， 则 FsRtlSupportsPerStreamContexts 宏返回 TRUE ，否则返回 FALSE 。

文件系统筛选器驱动程序调用 FsRtlSupportsPerStreamContexts ，以确定基础文件系统是否支持给定文件对象表示的文件流的每流上下文。请注意，对于某些类型的文件，文件系统可能支持按流上下文，但对于其他文件类型则不支持。例如，NTFS 和 FAT 目前不支持对文件进行分页的每个流上下文。

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