READ_USN_JOURNAL_DATA_V1 結構 (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;
WORD MinMajorVersion;
WORD MaxMajorVersion;
} READ_USN_JOURNAL_DATA_V1, *PREAD_USN_JOURNAL_DATA_V1;
成員
StartUsn
要開始閱讀變更日誌的USN。
若要在日誌的第一筆記錄啟動讀取作業，請將 StartUsn 成員設定為零。 因為 USN 包含在每個日誌記錄中，所以輸出緩衝區會告知讀取作業實際啟動的記錄。
若要在特定記錄啟動讀取作業，請將 StartUsn 設定為該記錄 USN。
如果指定的非零 USN 小於變更日誌中的第一個 USN，則會發生錯誤，並傳回 ERROR_JOURNAL_ENTRY_DELETED 錯誤碼。 此程式代碼可能表示指定的 USN 一次有效，但已刪除之後的情況。
如需流覽READ_USN_JOURNAL_DATA_V0中所傳回之變更日誌緩衝區的詳細資訊，請參閱逐步解說變更 日誌 記錄的緩衝區。
ReasonMask
旗標的遮罩，每個旗標都會指出檔案或目錄在變更日誌中有記錄的變更。 若要在 FSCTL_READ_USN_JOURNAL 作業中傳回，變更日誌記錄必須至少設定其中一個旗標。
有效旗標的清單如下所示。 未使用的位是保留的。
| 值 | 意義 |
|---|---|
|
用戶已變更一或多個檔案或目錄屬性 (，例如只讀、隱藏、系統、封存或疏鬆屬性) 或一或多個時間戳。 |
|
檔案或目錄已關閉。 |
|
檔案或目錄的壓縮狀態會從 或 變更為壓縮狀態。 |
|
檔案或目錄會新增至 。 |
|
檔案或目錄中的數據會遭到覆寫。 |
|
檔案或目錄已截斷。 |
|
用戶對檔案或目錄擴充屬性進行變更。 Windows 應用程式無法存取這些NTFS檔案系統屬性。 |
|
檔案或目錄已加密或解密。 |
|
第一次建立檔案或目錄。 |
|
檔案或目錄已刪除。 |
|
NTFS 檔系統硬連結會新增至或移除檔案或目錄。 NTFS 檔系統硬式連結，類似於 POSIX 硬連結，是看到相同檔案或目錄之一的數個目錄專案之一。 |
|
用戶已變更 FILE_ATTRIBUTE_NOT_CONTENT_INDEXED 屬性。 也就是說，使用者已將檔案或目錄從可編製索引的內容變更為無法編製索引的檔案或目錄，反之亦然。 (內容索引可藉由建置所選 content 的資料庫來快速搜尋數據。) |
|
已新增檔案的一或多個具名數據流。 |
|
會覆寫檔案的一或多個具名數據流中的數據。 |
|
檔案的一或多個具名數據流會被截斷。 |
|
檔案或目錄的物件標識碼已變更。 |
|
檔案或目錄已重新命名，而保留此日誌記錄的 USN_RECORD_V2 或 USN_RECORD_V3 結構中的檔名是新的名稱。 |
|
檔案或目錄已重新命名，且保存此日誌記錄的 USN_RECORD_V2 或 USN_RECORD_V3 結構中的檔名是先前的名稱。 |
|
檔案或目錄中所包含的重新分析點已變更，或重新分析點新增至檔案或目錄中或刪除。 |
|
變更檔案或目錄的訪問許可權。 |
|
具名數據流會新增至檔案或目錄或從檔案或目錄中移除，或已重新命名的數據流。 |
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。
MinMajorVersion
MaxMajorVersion
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows XP [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2003 [僅限桌面應用程式] |
| 標頭 | winioctl.h (包含 Windows.h) |