FltCreateSectionForDataScan 函数（fltkernel.h）

项目
12/21/2024

FltCreateSectionForDataScan 例程为文件创建节对象。筛选器管理器可以选择将 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

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

[in] SectionContext

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

[in] DesiredAccess

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

旗	允许调用方
SECTION_MAP_READ	阅读该部分的视图。
SECTION_MAP_WRITE	写入分区的视图。
SECTION_QUERY	查询节对象以获取有关该节的信息。驱动程序应设置此标志。
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

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

[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 将句柄插入到调用 FltCreateSectionForDataScan 的线程的进程句柄表中（SectionHandle）。

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

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

注意

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

如果不再需要此例程创建的 section 对象，请务必通过调用 ZwClose 例程来关闭节对象的句柄（SectionHandle），并通过调用 ObDereferenceObject 例程来取消引用节对象本身（SectionObject）。

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

重要

微型筛选器不得显式删除传递给 FltCreateSectionForDataScan的节上下文。在节上下文传递到 FltCreateSectionForDataScan后，请勿调用 FltDeleteContext。在本例中，通过调用 FltCloseSectionForDataScan 从流中解除分配和删除节上下文。

一般情况下，部分应创建为只读。具体而言，如果只读文件位于事务中，并且微型筛选器不创建只读节，则会放弃对节的写入，并且不会作为事务的一部分包含在内。