FltNotifyFilterChangeDirectory 函式 (fltkernel.h)

發行項
02/26/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作業。