FltNotifyFilterChangeDirectory 函数 (fltkernel.h)

项目
02/29/2024

FltNotifyFilterChangeDirectory 例程为IRP_MN_NOTIFY_CHANGE_DIRECTORY操作创建通知结构，并将其添加到指定的通知列表。

语法

VOID FLTAPI FltNotifyFilterChangeDirectory(
  [in, out]      PNOTIFY_SYNC               NotifySync,
  [in, out]      PLIST_ENTRY                NotifyList,
  [in]           PVOID                      FsContext,
  [in]           PSTRING                    FullDirectoryName,
  [in]           BOOLEAN                    WatchTree,
  [in]           BOOLEAN                    IgnoreBuffer,
  [in]           ULONG                      CompletionFilter,
  [in]           PFLT_CALLBACK_DATA         NotifyCallbackData,
  [in, optional] PCHECK_FOR_TRAVERSE_ACCESS TraverseCallback,
  [in, optional] PSECURITY_SUBJECT_CONTEXT  SubjectContext,
  [in, optional] PFILTER_REPORT_CHANGE      FilterCallback
);

参数

[in, out] NotifySync

指向 NotifyList 参数指向的更改目录通知列表的不透明同步对象的指针。

[in, out] NotifyList

指向当前卷的更改目录通知列表的头的指针。列表中的每个元素都是一个不透明的通知结构。

[in] FsContext

指向调用方分配的唯一值的指针，用于标识要创建的通知结构。如果在 TraverseCallback 参数中提供了回调例程， FsContext 将作为 NotifyContext 参数传递给该例程。

[in] FullDirectoryName

指向 ANSI 或 Unicode 字符串的指针，该字符串包含与此通知结构关联的目录的全名。

[in] WatchTree

如果还应监视 FullDirectoryName 参数指定的目录的所有子目录，则设置为 TRUE。如果仅监视目录本身，则设置为 FALSE 。

[in] IgnoreBuffer

设置为 TRUE 可忽略任何用户缓冲区并强制重新提供目录。此操作可加快操作速度。

[in] CompletionFilter

指定文件或目录更改类型的标志的位掩码，这些更改应导致通知列表中的回调数据结构完成。下表介绍了可能的标志值。

标志	含义
FILE_NOTIFY_CHANGE_FILE_NAME	已在此目录中添加、删除或重命名文件。
FILE_NOTIFY_CHANGE_DIR_NAME	已创建、删除或重命名子目录。
FILE_NOTIFY_CHANGE_NAME	此目录的名称已更改。
FILE_NOTIFY_CHANGE_ATTRIBUTES	此文件的某个属性的值（例如上次访问时间）已更改。
FILE_NOTIFY_CHANGE_SIZE	此文件的大小已更改。
FILE_NOTIFY_CHANGE_LAST_WRITE	此文件的上次修改时间已更改。
FILE_NOTIFY_CHANGE_LAST_ACCESS	此文件的上次访问时间已更改。
FILE_NOTIFY_CHANGE_CREATION	此文件的创建时间已更改。
FILE_NOTIFY_CHANGE_EA	此文件的扩展属性已修改。
FILE_NOTIFY_CHANGE_SECURITY	此文件的安全信息已更改。
FILE_NOTIFY_CHANGE_STREAM_NAME	已在此目录中添加、删除或重命名文件流。
FILE_NOTIFY_CHANGE_STREAM_SIZE	此文件流的大小已更改。
FILE_NOTIFY_CHANGE_STREAM_WRITE	此文件流的数据已更改。

[in] NotifyCallbackData

指向要添加到通知列表的操作的回调数据结构的指针。此参数是必需的，不能为 NULL。

[in, optional] TraverseCallback

指向在目录树中监视的子目录中发生更改时要调用的回调例程的可选指针。此指针允许文件系统检查观察程序是否具有对该目录的遍历访问权限。此类调用方提供的例程声明如下：

NTSTATUS
(*PCHECK_FOR_TRAVERSE_ACCESS) (
    IN PVOID NotifyContext,                     // FsContext
    IN PVOID TargetContext,                     // Context pointer
    IN PSECURITY_SUBJECT_CONTEXT SubjectContext // SubjectContext
    );

有关 TargetContext 参数的详细信息，请参阅 FsRtlNotifyFullReportChange 例程的 TargetContext 参数。

[in, optional] SubjectContext

指向要传递给 TraverseCallback 的上下文结构的指针。 FltNotifyFilterChangeDirectory 释放上下文并在使用结构后释放该结构。如果提供了 TraverseCallback 例程， 则 SubjectContext 作为 SubjectContext 参数传递给该例程。

[in, optional] FilterCallback

指向在目录发生更改时要调用的回调例程的可选指针。如果此回调例程返回 TRUE，FsRtlNotifyFilterReportChange 将完成通知列表中的挂起IRP_MN_NOTIFY_CHANGE_DIRECTORY操作;否则，它不会。此类调用方提供的例程声明如下：

BOOLEAN
(*PFILTER_REPORT_CHANGE) (
    IN PVOID NotifyContext,                     // FsContext
    IN PVOID FilterContext                      // Context pointer
    );

返回值

无

备注

微筛选器驱动程序可以从预操作回调例程调用 FltNotifyFilterChangeDirectory ， (PFLT_PRE_OPERATION_CALLBACK) 它已注册以处理通知更改目录操作。这些操作的主要函数代码为 IRP_MJ_DIRECTORY_CONTROL ，次要函数代码为 IRP_MN_NOTIFY_CHANGE_DIRECTORY。

微筛选器驱动程序调用 FltNotifyFilterChangeDirectory 来创建通知结构来保存操作的回调数据结构，并将通知结构添加到当前卷的通知列表中。

FltNotifyFilterChangeDirectory 执行以下操作：

检查操作的文件对象是否已清理。如果是这样， FltNotifyFilterChangeDirectory 将完成状态STATUS_NOTIFY_CLEANUP操作，并且不会将其添加到通知列表。
如果操作的文件对象尚未清理， 则 FltNotifyFilterChangeDirectory 会检查通知列表是否已包含给定 FsContext 值的通知结构。如果找到此类通知结构，并且有挂起的报表更改， FltNotifyFilterChangeDirectory 将完成 NotifyCallbackData 参数指向的回调数据结构。如果找到通知结构，但报表没有挂起的更改， 则 FltNotifyFilterChangeDirectory 会将操作添加到通知结构。如果未找到此类通知结构， FltNotifyFilterChangeDirectory 会为操作创建一个通知结构，并将其插入列表中。

当目录发生更改时，文件系统会调用 FsRtlNotifyFilterReportChange 来完成通知列表中的挂起IRP_MN_NOTIFY_CHANGE_DIRECTORY操作。