READ_USN_JOURNAL_DATA_V0結構 (winioctl.h)

  • 發行項

包含定義一組更新序號的資訊， (USN) 變更日誌記錄以返回呼叫進程。 它由 FSCTL_QUERY_USN_JOURNAL 和 FSCTL_READ_USN_JOURNAL 控制項程式碼使用。 在Windows 8和Windows Server 2012此結構命名READ_USN_JOURNAL_DATA之前。 使用該名稱以舊版 SDK 和編譯器進行編譯。 Windows Server 2012引進了 READ_USN_JOURNAL_DATA_V1，以支援 ReFS 所使用的 128 位檔案識別碼。

語法

typedef struct {
  USN       StartUsn;
  DWORD     ReasonMask;
  DWORD     ReturnOnlyOnClose;
  DWORDLONG Timeout;
  DWORDLONG BytesToWaitFor;
  DWORDLONG UsnJournalID;
} READ_USN_JOURNAL_DATA_V0, *PREAD_USN_JOURNAL_DATA_V0;

成員

StartUsn

要開始閱讀變更日誌的 USN。

若要在日誌中的第一筆記錄啟動讀取作業，請將 StartUsn 成員設定為零。 由於 USN 包含在每個日誌記錄中，因此輸出緩衝區會告知讀取作業實際啟動的記錄。

若要在特定記錄啟動讀取作業，請將 StartUsn 設定為該記錄 USN。

如果指定了小於變更日誌中第一個 USN 的非零 USN，則會發生錯誤，並傳回 ERROR_JOURNAL_ENTRY_DELETED 錯誤碼。 此程式碼可能表示指定的 USN 一次有效，但自刪除之後。

如需流覽 READ_USN_JOURNAL_DATA_V0中傳回之變更日誌緩衝區的詳細資訊，請參閱 逐步解說變更日誌記錄的緩衝區。

ReasonMask

旗標的遮罩，每個旗標都會指出檔案或目錄在變更日誌中有記錄的變更。 若要在 FSCTL_READ_USN_JOURNAL 作業中傳回，變更日誌記錄必須至少設定其中一個旗標。

有效的旗標清單如下所示。 未使用的位會保留。

值 意義
USN_REASON_BASIC_INFO_CHANGE
0x00008000
 使用者已變更一或多個檔案或目錄屬性 (，例如唯讀、隱藏、系統、封存或疏鬆屬性) 或一或多個時間戳記。
USN_REASON_CLOSE
0x80000000
 檔案或目錄已關閉。
USN_REASON_COMPRESSION_CHANGE
0x00020000
 檔案或目錄的壓縮狀態會從 或 變更為壓縮。
USN_REASON_DATA_EXTEND
0x00000002
 檔案或目錄會新增至 。
USN_REASON_DATA_OVERWRITE
0x00000001
 檔案或目錄中的資料會遭到覆寫。
USN_REASON_DATA_TRUNCATION
0x00000004
 檔案或目錄已截斷。
USN_REASON_EA_CHANGE
0x00000400
 使用者對檔案或目錄擴充屬性進行變更。 Windows 應用程式無法存取這些 NTFS 檔案系統屬性。
USN_REASON_ENCRYPTION_CHANGE
0x00040000
 檔案或目錄已加密或解密。
USN_REASON_FILE_CREATE
0x00000100
 檔案或目錄第一次建立。
USN_REASON_FILE_DELETE
0x00000200
 檔案或目錄已刪除。
USN_REASON_HARD_LINK_CHANGE
0x00010000
 NTFS 檔案系統硬式連結會新增至檔案或目錄，或從檔案或目錄移除。 NTFS 檔案系統硬式連結，類似于 POSIX 硬式連結，是看到相同檔案或目錄的數個目錄專案之一。
USN_REASON_INDEXABLE_CHANGE
0x00004000
 使用者已變更 FILE_ATTRIBUTE_NOT_CONTENT_INDEXED 屬性。 也就是說，使用者已將檔案或目錄從可編制索引的內容變更為無法編制索引的檔案或目錄，反之亦然。 (內容索引編制允許藉由建置所選 content 的資料庫來快速搜尋資料。)
USN_REASON_NAMED_DATA_EXTEND
0x00000020
 已新增檔案的一或多個具名資料流程。
USN_REASON_NAMED_DATA_OVERWRITE
0x00000010
 會覆寫檔案的一或多個具名資料流程中的資料。
USN_REASON_NAMED_DATA_TRUNCATION
0x00000040
 會截斷檔案的一或多個具名資料流程。
USN_REASON_OBJECT_ID_CHANGE
0x00080000
 檔案或目錄的物件識別碼已變更。
USN_REASON_RENAME_NEW_NAME
0x00002000
 檔案或目錄已重新命名，且保存此日誌記錄的USN_RECORD_V2或USN_RECORD_V3結構中的檔案名是新名稱。
USN_REASON_RENAME_OLD_NAME
0x00001000
 檔案或目錄已重新命名，且保存此日誌記錄的USN_RECORD_V2或USN_RECORD_V3結構中的檔案名是先前的名稱。
USN_REASON_REPARSE_POINT_CHANGE
0x00100000
 檔案或目錄中所包含的重新分析點已變更，或重新分析點會新增至檔案或目錄中或刪除。
USN_REASON_SECURITY_CHANGE
0x00000800
 變更檔案或目錄的存取權限。
USN_REASON_STREAM_CHANGE
0x00200000
 具名資料流程會新增至檔案或目錄或移除，或重新命名資料流程。

ReturnOnlyOnClose

值，指定何時傳回變更日誌記錄。

若要在關閉變更檔案或目錄的最終控制碼時收到通知，而不是在發生變更時，請將ReturnOnlyOnClose設定為任何非零值，並在ReasonMask成員中指定USN_REASON_CLOSE旗標。

當檔案關閉時， ReasonMask 旗標所指出的所有變更最終都會產生變更日誌軟體的呼叫。 如果您的 DeviceIoControl 呼叫正在等候檔案關閉，該呼叫會接著允許您的 DeviceIoControl 呼叫傳回。 如果檔案或目錄在磁片區失敗、作業系統失敗或關機之前未關閉，下次掛接磁片區時，就會發生變更日誌軟體的清除呼叫。 即使有中間的系統重新開機，也會發生呼叫。

若要在第一次記錄變更時收到通知，以及清除時，請將 ReturnOnlyOnClose 設定為零。

ReturnOnlyOnClose是否為零或非零，在變更日誌內清除記錄檔中產生的記錄，都是發生于檔案或目錄的 USN 變更原因。 每次專案發生最終關閉作業時，都會將 USN 關閉記錄寫入變更日誌，而專案的 ReasonMask 旗標全都會重設。

例如，對於沒有任何使用者資料的檔案或目錄 (，掛接的資料夾) ，在最後一個使用者控制碼上呼叫 CloseHandle 函式時，就會發生最終關閉作業。

Timeout

與 BytesToWaitFor 成員搭配使用的逾時值，告知作業系統如果 FSCTL_READ_USN_JOURNAL 作業要求的資料比變更日誌中還多，該怎麼辦。

如果 Timeout 為零且 BytesToWaitFor 為非零，且 FSCTL_READ_USN_JOURNAL 作業呼叫到達變更日誌的結尾，而不需尋找要傳回的資料， FSCTL_READ_USN_JOURNAL 等到未篩選資料的 BytesToWaitFor 位元組已新增至變更日誌，然後擷取指定的記錄。

如果 Timeout 為非零且 BytesToWaitFor 為非零，且 FSCTL_READ_USN_JOURNAL 作業呼叫會到達變更日誌的結尾，而不需尋找要傳回的資料， FSCTL_READ_USN_JOURNAL 等候 Timeout 秒，然後嘗試傳回指定的記錄。 在 逾時 秒之後， FSCTL_READ_USN_JOURNAL 擷取指定範圍內可用的任何記錄。

不論是哪一種情況，在逾時期間之後，就會處理任何附加至變更日誌的新資料。 如果尚未從指定的集合傳回任何記錄，則會重複逾時期間。 在此模式中， FSCTL_READ_USN_JOURNAL 維持未完成狀態，直到至少傳回一筆記錄或取消 I/O 為止。

如果 BytesToWaitFor 為零，則會忽略 Timeout 。 非同步開啟的控制碼也會忽略逾時。

BytesToWaitFor

新增至變更日誌之未篩選資料的位元組數目。 使用這個值搭配 Timeout 來告訴作業系統，如果 FSCTL_READ_USN_JOURNAL 作業要求的資料比變更日誌中還多，該怎麼辦。

如果 BytesToWaitFor 為零，則會忽略 Timeout 。 在此情況下，發生變更日誌檔案結尾時， FSCTL_READ_USN_JOURNAL 作業一律會成功傳回。 它也會擷取應該用於下一 個FSCTL_READ_USN_JOURNAL 作業的 USN。 當傳回的下一個 USN 與提供的 StartUsn 相同時，沒有可用的記錄。 呼叫進程不應該立即使用 FSCTL_READ_USN_JOURNAL 。

由於 當 BytesToWaitFor 為零時，無法預測傳回的資料量，因此您會執行溢位輸出緩衝區的風險。 若要降低此風險，請在重複的FSCTL_READ_USN_JOURNAL作業中指定非零的 BytesToWaitFor值，直到變更日誌中的所有記錄耗盡為止。 然後指定零以等候新記錄。

或者，在FSCTL_READ_USN_JOURNAL作業呼叫中使用DeviceIoControl的lpBytesReturned參數來判斷可用的資料量、使用空間重新配置輸出緩衝區 (以備援新記錄) ，然後再次呼叫DeviceIoControl。

UsnJournalID

磁片區目前之日誌實例的識別碼。

如果變更日誌停止並重新啟動或刪除並重新建立變更日誌，NTFS 檔案系統可能會遺漏將事件放入變更日誌中。 如果發生其中一個事件，NTFS 檔案系統會提供日誌新的識別碼。 如果日誌識別碼與目前的日誌識別碼不一致， 則對 DeviceIoControl 的呼叫會失敗，並傳回適當的錯誤碼。 若要擷取新的日誌識別碼，請使用FSCTL_QUERY_USN_JOURNAL作業呼叫DeviceIoControl。

規格需求

   
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2003 [僅限傳統型應用程式]
標頭 winioctl.h (包含 Windows.h)

另請參閱

FSCTL_QUERY_USN_JOURNAL

FSCTL_READ_USN_JOURNAL

USN_RECORD