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、ReFS で使用される 128 ビットのファイル識別子をサポートするREAD_USN_JOURNAL_DATA_V1が導入されました。
構文
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 メンバーを 0 に設定します。 USN はすべてのジャーナル レコードに含まれているため、出力バッファーは、読み取り操作が実際に開始されたレコードを示します。
特定のレコードで読み取り操作を開始するには、 StartUsn をそのレコード USN に設定します。
変更ジャーナルの最初の USN より小さい 0 以外の USN が指定されている場合は、エラーが発生し、 ERROR_JOURNAL_ENTRY_DELETED エラー コードが返されます。 このコードは、指定された USN が一度に有効であるが、その後削除されたケースを示している可能性があります。
READ_USN_JOURNAL_DATA_V0で返される変更ジャーナル バッファー内を移動する方法の詳細については、「変更履歴レコードのバッファーの移動」を参照してください。
ReasonMask
フラグのマスク。各フラグは、ファイルまたはディレクトリーが変更ジャーナルにレコードを持つ変更を示します。 FSCTL_READ_USN_JOURNAL操作で戻すには、変更ジャーナル・レコードに少なくとも 1 つのフラグが設定されている必要があります。
有効なフラグの一覧は次のとおりです。 未使用のビットは予約されています。
| 値 | 意味 |
|---|---|
|
ユーザーが 1 つ以上のファイル属性またはディレクトリ属性 (読み取り専用、非表示、システム、アーカイブ、スパース属性など)、または 1 つ以上のタイム スタンプを変更しました。 |
|
ファイルまたはディレクトリが閉じられています。 |
|
ファイルまたはディレクトリの圧縮状態は、 または から圧縮に変更されます。 |
|
ファイルまたはディレクトリが に追加されます。 |
|
ファイルまたはディレクトリ内のデータが上書きされます。 |
|
ファイルまたはディレクトリが切り捨てられます。 |
|
ユーザーは、ファイルまたはディレクトリ拡張属性を変更します。 これらの NTFS ファイル システム属性は、Windows ベースのアプリケーションではアクセスできません。 |
|
ファイルまたはディレクトリは暗号化または暗号化解除されます。 |
|
ファイルまたはディレクトリは初めて作成されます。 |
|
ファイルまたはディレクトリが削除されます。 |
|
NTFS ファイル システムのハード リンクは、ファイルまたはディレクトリに追加されるか、ファイルまたはディレクトリから削除されます。 POSIX ハード リンクと同様に、NTFS ファイル システムのハード リンクは、同じファイルまたはディレクトリを参照する複数のディレクトリ エントリの 1 つです。 |
|
ユーザーが FILE_ATTRIBUTE_NOT_CONTENT_INDEXED 属性を変更しました。 つまり、ユーザーは、コンテンツインデックスを作成できるファイルまたはディレクトリから、インデックスを作成できないファイルまたはディレクトリに変更しました。その逆も可能です。 (コンテンツ インデックス作成を使用すると、選択したコンテンツのデータベースを作成して、データを迅速に検索できます。 |
|
ファイルの名前付きデータ ストリームが 1 つ以上追加されました。 |
|
ファイルの 1 つ以上の名前付きデータ ストリーム内のデータが上書きされます。 |
|
ファイルの 1 つ以上の名前付きデータ ストリームが切り捨てられます。 |
|
ファイルまたはディレクトリのオブジェクト識別子が変更されます。 |
|
ファイルまたはディレクトリーの名前が変更され、このジャーナル・レコードを保持 するUSN_RECORD_V2 または USN_RECORD_V3 構造内のファイル名が新しい名前になります。 |
|
ファイルまたはディレクトリーの名前が変更され、このジャーナル・レコードを保持 するUSN_RECORD_V2 または USN_RECORD_V3 構造内のファイル名が前の名前になります。 |
|
ファイルまたはディレクトリに含まれる再解析ポイントが変更されるか、ファイルまたはディレクトリに再解析ポイントが追加または削除されます。 |
|
ファイルまたはディレクトリへのアクセス許可に変更が加えられます。 |
|
名前付きストリームがファイルまたはディレクトリに追加または削除されるか、名前付きストリームの名前が変更されます。 |
ReturnOnlyOnClose
変更履歴レコードを返すタイミングを示す 値です。
変更されたファイルまたはディレクトリの最後のハンドルが閉じられたときに通知を受け取る場合は、変更が発生した時点ではなく、ReturnOnlyOnClose を 0 以外の値に設定し、ReasonMask メンバーで USN_REASON_CLOSE フラグを指定します。
ReasonMask フラグによって示されるすべての変更は、ファイルが閉じられると、最終的に変更ジャーナル ソフトウェアの呼び出しを生成します。 DeviceIoControl 呼び出しでファイルが閉じられるのを待機している場合、その呼び出しによって DeviceIoControl 呼び出しが返されます。 ボリューム障害、オペレーティング・システム障害、またはシャットダウンの前にファイルまたはディレクトリーがクローズされなかった場合は、次回ボリュームがマウントされるときに、変更ジャーナル・ソフトウェアのクリーンアップ呼び出しが行われます。 この呼び出しは、システムの再起動が間に合っている場合でも発生します。
各変更が初めてログに記録されるだけでなく、クリーンアップ時にも通知を受け取る場合は、 ReturnOnlyOnClose を 0 に設定します。
ReturnOnlyOnClose が 0 であるか 0 以外であるかに関係なく、変更ジャーナル内のクリーンアップ ログで生成されるレコードは、ファイルまたはディレクトリに対して USN が変更された理由をすべて示します。 項目に対して最後のクローズ操作が行われるたびに、USN クローズ・レコードが変更ジャーナルに書き込まれ、項目の ReasonMask フラグがすべてリセットされます。
ユーザー データが存在しないファイルまたはディレクトリ (マウントされたフォルダーなど) の場合、最後の close 操作は、アイテムに対する最後のユーザー ハンドルで CloseHandle 関数が呼び出されたときに発生します。
Timeout
FSCTL_READ_USN_JOURNAL操作が変更ジャーナルに存在するデータよりも多くのデータを要求した場合の対処方法をオペレーティング システムに指示するために BytesToWaitFor メンバーと共に使用されるタイムアウト値 (秒単位)。
Timeout が 0 で BytesToWaitFor が 0 以外の場合、FSCTL_READ_USN_JOURNAL操作の呼び出しが、返されるデータを見つけずに変更ジャーナルの末尾に達した場合、FSCTL_READ_USN_JOURNALは、フィルター処理されていないデータの BytesToWaitFor バイトが変更ジャーナルに追加されるまで待機し、指定されたレコードを取得します。
Timeout が 0 以外で BytesToWaitFor が 0 以外の場合、FSCTL_READ_USN_JOURNAL操作の呼び出しが、返されるデータを見つけずに変更ジャーナルの末尾に達した場合、FSCTL_READ_USN_JOURNALは Timeout 秒を待機し、指定されたレコードを返そうとします。 タイムアウト秒数が経過すると、FSCTL_READ_USN_JOURNALは、指定された範囲内で使用可能なすべてのレコードを取得します。
いずれの場合も、タイムアウト期間の後に、変更履歴に追加された新しいデータが処理されます。 指定したセットから返すレコードがまだない場合は、タイムアウト期間が繰り返されます。 このモードでは、 少 なくとも 1 つのレコードが返されるか、I/O が取り消されるまで、FSCTL_READ_USN_JOURNALは未処理のままになります。
BytesToWaitFor が 0 の場合、Timeout は無視されます。 非同期に開かれたハンドルの場合も、タイムアウトは無視されます。
BytesToWaitFor
変更ジャーナルに追加されたフィルター処理されていないデータのバイト数。 この値を Timeout と共に使用して、 FSCTL_READ_USN_JOURNAL 操作が変更ジャーナルに存在するデータよりも多くのデータを要求した場合の対処方法をオペレーティング システムに指示します。
BytesToWaitFor が 0 の場合、Timeout は無視されます。 この場合、変更ジャーナル・ファイルの終了が検出されると、 FSCTL_READ_USN_JOURNAL 操作は常に正常に戻ります。 また、次の FSCTL_READ_USN_JOURNAL 操作に使用する必要がある USN も取得します。 返された次の USN が指定された StartUsn と同じ場合、使用できるレコードはありません。 呼び出し元のプロセスでは 、 FSCTL_READ_USN_JOURNALをすぐに使用しないでください。
BytesToWaitFor が 0 の場合、返されるデータの量を予測できないため、出力バッファーがオーバーフローするリスクがあります。 このリスクを軽減するには、変更ジャーナル内のすべてのレコードが使い果たされるまで、繰り返されるFSCTL_READ_USN_JOURNAL操作で 0 以外の BytesToWaitFor 値を指定します。 次に、新しいレコードを待機するには、0 を指定します。
または、FSCTL_READ_USN_JOURNAL操作呼び出しで DeviceIoControl の lpBytesReturned パラメーターを使用して、使用可能なデータの量を確認し、出力バッファーを再割り当てして (新しいレコードに余裕を持って)、DeviceIoControl をもう一度呼び出します。
UsnJournalID
ボリュームの現在のジャーナルのインスタンスの識別子。
変更ジャーナルが停止され、再開または削除されて再作成された場合、NTFS ファイル・システムは変更ジャーナルにイベントを入れなくなる可能性があります。 これらのイベントのいずれかが発生した場合、NTFS ファイル システムはジャーナルに新しい識別子を与えます。 ジャーナル ID が現在のジャーナル識別子と一致しない場合、 DeviceIoControl の呼び出しは失敗し、適切なエラー コードが返されます。 新しいジャーナル識別子を取得するには、FSCTL_QUERY_USN_JOURNAL操作で DeviceIoControl を呼び出します。
要件
| サポートされている最小のクライアント | Windows XP [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2003 [デスクトップ アプリのみ] |
| ヘッダー | winioctl.h (Windows.h を含む) |