MARK_HANDLE_INFO構造体 (winioctl.h)

  • [アーティクル]

指定したファイルまたはディレクトリのマークに使用される情報と、その更新シーケンス番号 (USN) 変更履歴レコードに変更に関するデータが含まれます。 これは、FSCTL_MARK_HANDLE コントロール コードによって使用されます。

構文

typedef struct _MARK_HANDLE_INFO {
  union {
    DWORD UsnSourceInfo;
    DWORD CopyNumber;
  } DUMMYUNIONNAME;
  DWORD  UsnSourceInfo;
  HANDLE VolumeHandle;
  DWORD  HandleInfo;
} MARK_HANDLE_INFO, *PMARK_HANDLE_INFO;

メンバーズ

DUMMYUNIONNAME

DUMMYUNIONNAME.UsnSourceInfo

DUMMYUNIONNAME.CopyNumber

UsnSourceInfo

行われる変更の種類。

この操作では、ファイルまたはディレクトリを作成したアプリケーションの観点から外部から変更されることはありません。

スレッドが新しい USN レコードを書き込むとき、以前のレコードのソース情報フラグは、スレッドがそれらのフラグも設定した場合にのみ存在し続けます。 したがって、ソース情報構造を使用すると、アプリケーションは、ウイルス対策フィルターなどの既知のソースによってのみ設定された USN レコードを除外できます。

次の値が定義されています。

価値 意味
USN_SOURCE_DATA_MANAGEMENT
0x00000001
 この操作は、オペレーティング システムによって行われたファイルまたはディレクトリの変更に関する情報を提供します。

一般的な用途は、リモート ストレージが外部ストレージからローカル ストレージにデータを移動する場合です。 リモート ストレージは、階層型ストレージ管理ソフトウェアです。 このような移動は通常、少なくとも USN レコードに USN_REASON_DATA_OVERWRITE フラグを追加します。 ただし、データはユーザーの観点から変更されていません。 レコードを保持する USN_RECORD 構造体の SourceInfo メンバー内の USN_SOURCE_DATA_MANAGEMENT を書き込むことで、アイテムに対して書き込み操作が実行されているにもかかわらず、データが変更されていないことを確認できます。
USN_SOURCE_AUXILIARY_DATA
0x00000002
 この操作により、プライベート データ ストリームがファイルまたはディレクトリに追加されます。

たとえば、チェックサム情報を追加するウイルス検出機能があります。 ウイルス検出機能が項目を変更すると、システムは USN レコードを生成します。 USN_SOURCE_AUXILIARY_DATA は、変更によってアプリケーション データが変更されなかったことを示します。
USN_SOURCE_REPLICATION_MANAGEMENT
0x00000004
 この操作により、レプリケートされたファイルの内容が作成または更新されます。

たとえば、ファイル レプリケーション サービスは、レプリケートされたディレクトリ内のファイルを作成または更新するときに、このフラグを設定します。
USN_SOURCE_CLIENT_REPLICATION_MANAGEMENT
0x00000008
 レプリケーションは、クラウドまたはサーバーからクライアント システムで実行されています。

VolumeHandle

ファイルまたはディレクトリが存在するボリュームへのボリューム ハンドル。 ボリューム ハンドルの取得の詳細については、「解説」セクションを参照してください。

この操作の権限を確認するには、このハンドルが必要です。

呼び出し元には、SE_MANAGE_VOLUME_NAME 特権が必要です。 詳細については、「Privileges」を参照してください。

HandleInfo

VolumeHandle メンバーのハンドル値によって識別されるファイルまたはディレクトリに関する追加情報を指定するフラグ。

価値 意味
MARK_HANDLE_PROTECT_CLUSTERS
0x00000001
 ファイルは、ハンドルが閉じられるまで最適化できないとマークされます。

MARK_HANDLE_PROTECT_CLUSTERS マークされたハンドルが閉じられると、ファイルのクラスターが移動しないという保証はありません。
MARK_HANDLE_TXF_SYSTEM_LOG
0x00000004
 ファイルは、ハンドルが閉じられるまで最適化できないとマークされます。

Windows Server 2003: このフラグは、Windows Server 2003 SP1 までサポートされていません。

Windows XP: このフラグはサポートされていません。
MARK_HANDLE_NOT_TXF_SYSTEM_LOG
0x00000008
 ファイルは、ハンドルが閉じられるまで最適化できないとマークされます。

Windows Server 2003: このフラグは、Windows Server 2003 SP1 までサポートされていません。

Windows XP: このフラグはサポートされていません。
MARK_HANDLE_REALTIME
0x00000020
 ファイルは、実際のファイルの種類に関係なく、リアルタイムの読み取り動作としてマークされます。 このフラグでマークされたファイルは、バッファーされていない I/O開く必要があります。

Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP: このフラグはサポートされていません。
MARK_HANDLE_NOT_REALTIME
0x00000040
 MARK_HANDLE_REALTIME フラグを使用して、以前にリアルタイム読み取り動作としてマークされたファイルは、このフラグを使用してマークを解除して、リアルタイムの動作を削除できます。 このフラグでマークされたファイルは、バッファーされていない I/O開く必要があります。

Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP: このフラグはサポートされていません。
MARK_HANDLE_READ_COPY
0x00000080
 CopyNumber メンバーで指定されたコピー番号を読み取りに使用する必要があることを示します。 このフラグでマークされたファイルは、バッファーされていない I/O開く必要があります。

Windows Server 2008 R2、Windows 7、Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP: このフラグは、Windows 8 および Windows Server 2012 までサポートされていません。
MARK_HANDLE_NOT_READ_COPY
0x00000100
 以前に MARK_HANDLE_READ_COPY フラグを使用して読み取り/コピー動作としてマークされたファイルは、このフラグを使用してマークを解除して、読み取り/コピー動作を削除できます。 このフラグでマークされたファイルは、バッファーされていない I/O開く必要があります。

Windows Server 2008 R2、Windows 7、Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP: このフラグは、Windows 8 および Windows Server 2012 までサポートされていません。
MARK_HANDLE_RETURN_PURGE_FAILURE
0x00000400
 キャッシュされていない IO とメモリ マップ済み/キャッシュされた IO を混在させると、システムは、キャッシュされていない IO が発行されたときに、キャッシュされていない IO の範囲のメモリ マッピングを消去しようとします。 これらの消去が失敗した場合、システムは通常、エラーを呼び出し元に返しません。これにより、状態が破損する可能性があります (このため、ドキュメントではこれを行わないと記載されています)。 このフラグは、アプリケーションがこの状況をより適切に処理できるように、特定のハンドルの消去エラーを返すようにシステムに指示します

このフラグは、Windows 8 および Windows Server 2012 までサポートされていません。
MARK_HANDLE_DISABLE_FILE_METADATA_OPTIMIZATION
0x00001000
 NTFS の高度に断片化されたファイルは、複数の MFT レコードを使用して、ファイルのすべてのエクステントを記述します。 この子 MFT レコードのリスト (FRS レコードとも呼ばれます) は、属性リストと呼ばれる構造によって制御されます。 属性リストのサイズは 128K に制限されています。 属性リストのサイズが特定のしきい値に達すると、NTFS によってエクステントのバックグラウンド圧縮がトリガーされ、子 FRS レコードの最小数が使用されます。 このフラグは、指定されたファイルに対するこの FRS 圧縮機能を無効にします。

このフラグは、Windows 10 までサポートされていません。
MARK_HANDLE_ENABLE_USN_SOURCE_ON_PAGING_IO
0x00002000
 USN Journal のページング書き込み時に、指定された UsnSourceInfo 値を設定するように NTFS に指示します。 従来、これはページング書き込みでは実行されませんでした。これは、指定された変更を行ったスレッドがシステムで認識されなかったためです。 これはオーバーライドです。 これは、メモリ マネージャーが使用している FileObject にこの状態が関連付けられている場合にのみ機能します。

このフラグは、Windows 10 までサポートされていません。
MARK_HANDLE_SKIP_COHERENCY_SYNC_DISALLOW_WRITES
0x00004000
 このフラグを設定すると、このファイルで書き込みが許可されていないことがシステムに通知されます。 アプリケーションが書き込みアクセスのためにファイルを開こうとすると、STATUS_ACCESS_DENIED操作は失敗します。 書き込みが見られた場合、操作はSTATUS_MARKED_TO_DISALLOW_WRITESで失敗します

このフラグは、Windows 10 までサポートされていません。

備考

ボリュームへのハンドルを取得するには、lpFileName パラメーターを次の形式の文字列に設定して CreateFile を呼び出します。

"\\.\X:"

上記の文字列では、X は、ボリュームが表示されるドライブを識別する文字です。

必要条件

要件 価値
サポートされる最小クライアント Windows XP [デスクトップ アプリのみ]
サポートされる最小サーバー Windows Server 2003 [デスクトップ アプリのみ]
ヘッダー winioctl.h (Windows.h を含む)

関連項目

FSCTL_MARK_HANDLE

USN_RECORD