FltCreateSectionForDataScan 函数 (fltkernel.h)

项目
02/29/2024

FltCreateSectionForDataScan 例程为文件创建一个 section 对象。筛选器管理器可以选择将 I/O 与创建的节同步。

语法

NTSTATUS FLTAPI FltCreateSectionForDataScan(
  [in]            PFLT_INSTANCE      Instance,
  [in]            PFILE_OBJECT       FileObject,
  [in]            PFLT_CONTEXT       SectionContext,
  [in]            ACCESS_MASK        DesiredAccess,
  [in, optional]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional]  PLARGE_INTEGER     MaximumSize,
  [in]            ULONG              SectionPageProtection,
  [in]            ULONG              AllocationAttributes,
  [in]            ULONG              Flags,
  [out]           PHANDLE            SectionHandle,
  [out]           PVOID              *SectionObject,
  [out, optional] PLARGE_INTEGER     SectionFileSize
);

参数

[in] Instance

要检索其上下文的微筛选器驱动程序实例的不透明实例指针。

[in] FileObject

打开的文件的文件对象。 section 对象将由指定的文件提供支持。此参数是必需的，不能为 NULL。

[in] SectionContext

指向以前分配的节上下文的指针。

[in] DesiredAccess

节对象的访问类型，作为以下一个或多个 ACCESS_MASK 标志。

标志	允许调用方访问
SECTION_MAP_READ	读取分区的视图。
SECTION_MAP_WRITE	写入节的视图。
SECTION_QUERY	查询 section 对象以获取有关节的信息。驱动程序应设置此标志。
SECTION_ALL_ACCESS	由前面的标志以及由 STANDARD_RIGHTS_REQUIRED 定义的所有操作。有关STANDARD_RIGHTS_REQUIRED的详细信息，请参阅 ACCESS_MASK。

[in, optional] ObjectAttributes

指向指定对象名称和其他属性的可选 OBJECT_ATTRIBUTES 结构的指针。使用 InitializeObjectAttributes 宏初始化此结构。

[in, optional] MaximumSize

此参数留待将来使用。

[in] SectionPageProtection

要放置在节中每个页面上的保护。指定以下值之一。此参数是必需的，不能为零。

标志	含义
PAGE_READONLY	启用对已提交页面区域的只读访问。尝试写入已提交区域会导致访问冲突。如果系统区分只读访问和执行访问，则尝试在已提交的区域中执行代码会导致访问冲突。
PAGE_READWRITE	启用对已提交页面区域的读取和写入访问。

[in] AllocationAttributes

SEC_XXX 标志的位掩码确定节的分配属性。指定以下一个或多个值。此参数是必需的，不能为零。

标志	含义
SEC_COMMIT	为分区的所有页面分配内存中或磁盘上的分页文件中的物理存储。这是默认设置。请注意，此标志是必需的，不能省略。
SEC_FILE	FileObject 参数指定的文件是映射文件。

[in] Flags

此参数留待将来使用。

[out] SectionHandle

指向调用方分配的变量的指针，该变量接收节的不透明句柄。默认情况下，节句柄是用户句柄。如果调用方需要内核句柄，则必须在 ObjectAttributes 参数中传递指向初始化的OBJECT_ATTRIBUTES结构的指针，并设置了OBJ_KERNEL_HANDLE标志。

[out] SectionObject

指向调用方分配的变量的指针，该变量接收指向 section 对象的不透明指针。

[out, optional] SectionFileSize

指向调用方分配的变量的指针，该变量在创建节对象时接收文件的大小（以字节为单位）。此参数是可选的，可以为 NULL。

返回值

FltCreateSectionForDataScan 返回STATUS_SUCCESS或相应的 NTSTATUS 值，例如以下值之一。

返回代码	说明
STATUS_END_OF_FILE	FileObject 参数指定的文件大小为零。
STATUS_FILE_LOCK_CONFLICT	FileObject 参数指定的文件已锁定。
STATUS_INSUFFICIENT_RESOURCES	FltCreateSectionForDataScan 遇到池分配失败。
STATUS_INVALID_FILE_FOR_SECTION	FileObject 参数指定的文件不支持节。
STATUS_INVALID_PARAMETER	未注册微筛选器。
STATUS_INVALID_PARAMETER_8	为 SectionPageProtection 参数指定的值无效。
STATUS_INVALID_PARAMETER_9	调用方为 AllocationAttributes 参数指定了无效值。
STATUS_NOT_SUPPORTED	附加到此实例的卷不支持节上下文。
STATUS_PRIVILEGE_NOT_HELD	调用方没有所需的权限来创建具有 DesiredAccess 参数中指定的访问权限的分区对象。
STATUS_FILE_IS_A_DIRECTORY	FileObject 参数指定的文件是目录。
STATUS_FLT_CONTEXT_ALREADY_DEFINED	实例指定的筛选器实例已为流打开了一个部分。每个流仅支持一个部分，因此支持每个实例。

注解

在调用 FltCreateSectionForDataScan 之前，微筛选器必须先通过调用 FltRegisterForDataScan 来注册其卷以便进行数据扫描。与其他筛选器上下文元素一样， SectionContext 首先使用 FltAllocateContext 进行分配。

FltCreateSectionForDataScan 将 sectionHandle () 对象句柄插入到调用 FltCreateSectionForDataScan 的线程的进程句柄表中。

句柄可以是用户句柄，也可以是内核句柄。在 ObjectAttributes 指向的 OBJECT_ATTRIBUTES 结构中设置OBJ_KERNEL_HANDLE创建的句柄是内核句柄，只能从内核模式进行访问。在没有OBJ_KERNEL_HANDLE标志的情况下创建的句柄是用户句柄，可以从用户或内核模式进行访问。筛选器可以创建用户句柄，然后将其传递给用户模式应用程序进行处理。例如，病毒扫描引擎可以位于用户模式应用程序中，并通过文件系统筛选器提供用户句柄。

在某些情况下，保留打开的节与当前文件 I/O 不兼容。具体而言，如果由于打开的节而阻止缓存清除，则触发缓存清除的文件 I/O 可能会导致缓存不一致。微筛选器可以为这些事件的通知提供可选的回调例程。微筛选器驱动程序实现 PFLT_SECTION_CONFLICT_NOTIFICATION_CALLBACK 来接收这些通知。如果在注册微筛选器时将 FLT_REGISTRATION 的 SectionNotificationCallback 成员设置为此回调例程，则会启用冲突通知。收到通知后，可以关闭节，以允许冲突的 I/O 操作继续。

注意

在 FltCreateSectionForDataScan 返回之前，可能会发生节通知回调。微筛选器必须能够接收回调并处理 SectionHandle 和 SectionObject 尚无效的情况。

如果不再需要此例程创建的 section 对象，请确保通过调用 ZwClose 例程关闭 section 对象的句柄 (SectionHandle) ，并通过调用 ObDereferenceObject 例程 (sectionObject) 取消引用 section 对象本身。

有关创建映射分区和内存视图的概述信息，请参阅节对象和视图。另请参阅Microsoft Windows SDK中的 CreateFileMapping 例程的文档。

重要

微筛选器不得显式删除传递给 FltCreateSectionForDataScan 的节上下文。不要在将节上下文传递到 FltCreateSectionForDataScan 后调用 FltDeleteContext。在这种情况下，通过调用 FltCloseSectionForDataScan ，将解除分配节上下文并将其从流中删除。

通常，应将分区创建为只读。具体而言，如果只读文件位于事务中，而微筛选器未创建只读节，则会放弃对节的写入，并且不会作为事务的一部分包含。