FSCTL_REQUEST_OPLOCK IOCTL (winioctl.h)

2025-02-21

ファイルに対して日和見ロック (oplock) を要求し、oplock の中断が発生したことを確認します。

この操作を実行するには、次のパラメーターを使用して DeviceIoControl 関数を呼び出します。

BOOL DeviceIoControl(
  (HANDLE) hDevice,                 // handle to file
  FSCTL_REQUEST_OPLOCK,             // dwIoControlCode
  (LPVOID) lpInBuffer,              // pointer to REQUEST_OPLOCK_INPUT_BUFFER
  (DWORD) nInBufferSize,            // size of input buffer
  (LPVOID) lpOutBuffer,             // pointer to REQUEST_OPLOCK_OUTPUT_BUFFER
  (DWORD) nOutBufferSize,           // size of output buffer
  NULL,                             // number of bytes returned
  (LPOVERLAPPED) lpOverlapped       // OVERLAPPED structure
);

備考

この操作は、ローカルサーバーから日和見ロック (oplock) を要求するためにクライアントアプリケーションによって使用されます。クライアントアプリケーションは、リモートサーバーに対して日和見ロックを直接要求してはなりません。ネットワークリダイレクターは、アプリケーションの日和見ロックを透過的に要求します。この操作を使用してリモートサーバーから日和見ロックを要求すると、要求が拒否されます。

DeviceIoControl 操作がエラーコード ERROR_IO_PENDINGを返す場合は、oplock 要求が許可されています。他のエラーコードが返された場合、oplock は許可されていません。エラーコードがERROR_CANNOT_GRANT_REQUESTED_OPLOCKなどの警告値である場合は、拡張情報が REQUEST_OPLOCK_OUTPUT_BUFFER 構造体で使用できる可能性があります。

許可された oplock が中断されると、OVERLAPPED 構造体内のイベントオブジェクトが通知され、REQUEST_OPLOCK_OUTPUT_BUFFER 構造体に情報が返されます。 OVERLAPPED 構造体の Internal メンバーは NTSTATUS 値に設定され、oplock がどのように壊れたかについての拡張情報を提供します。

オーバーラップ。内部値	意味
STATUS_SUCCESS 0x0	oplock が別のファイルシステム操作によって破損しました。
STATUS_OPLOCK_HANDLE_CLOSED 0x00000216	要求に使用されたファイルハンドルが閉じられたため、oplock は強制的に使用されなくなりました。要求に使用されたハンドルが閉じられたために oplock が中断した場合、oplock の種類に関係なく、中断を確認する必要はありません。
STATUS_OPLOCK_SWITCHED_TO_NEW_HANDLE 0x00000215	oplock は引き続き有効ですが、要求に使用されたファイルハンドルには関連付けなくなりました。呼び出し元がファイルに対して別のハンドルを使用して新しい oplock を要求し、そのハンドルが oplock を所有するようになりました。

FSCTL_REQUEST_OPLOCK コントロールコードは、関連するコントロールコード (FSCTL_REQUEST_OPLOCK_LEVEL_1、FSCTL_REQUEST_OPLOCK_LEVEL_2、FSCTL_REQUEST_FILTER_OPLOCK、FSCTL_REQUEST_BATCH_OPLOCK) よりも効率的な機能を提供します。異なるオペロックレベルの要求は、FSCTL_REQUEST_OPLOCKを使用するときにハンドルを閉じて再び開くことなく、同じハンドルで繰り返し実行できます。その他のコントロールコードでは、このような変更を行うために、ハンドルを閉じてから CreateFile で再度開く必要があります。これは、FSCTL_REQUEST_OPLOCK 制御コードを再発行するときに、REQUEST_OPLOCK_INPUT_BUFFER 構造体の RequestedOplockLevel メンバーを操作することによって実現されます。

次の表は、FSCTL_REQUEST_OPLOCK から使用できる oplock 型のキャッシュ機能が、レベル 2、レベル 1、バッチ oplock にどのように対応するかをまとめたものです。

代替制御コード	同等 RequestedOplockLevel フラグ値	Oplock 型
FSCTL_REQUEST_BATCH_OPLOCK	`OPLOCK_LEVEL_CACHE_READ \\| OPLOCK_LEVEL_CACHE_WRITE \\| OPLOCK_LEVEL_CACHE_HANDLE`	RWH
FSCTL_REQUEST_OPLOCK_LEVEL_1	`OPLOCK_LEVEL_CACHE_READ \\| OPLOCK_LEVEL_CACHE_WRITE`	RW
FSCTL_REQUEST_OPLOCK_LEVEL_2	`OPLOCK_LEVEL_CACHE_READ`	R

RequestedOplockLevel メンバーを OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE に設定して FSCTL_REQUEST_OPLOCK コントロールコードを使用すると、RH 型の oplock許可されます。 RH oplock は、FSCTL_REQUEST_FILTER_OPLOCK コントロールコードによって付与されるフィルター操作ロックに似ています。ただし、フィルター操作ロックでは、一度に 1 つのファイルに対して 1 つの oplock を保持できるクライアントは 1 つだけであることに注意してください。FSCTL_REQUEST_OPLOCK を使用すると、一度に複数のクライアントが RH ファイルをロックできます。もう 1 つの違いは、FSCTL_REQUEST_FILTER_OPLOCK は書き込みを行う前に oplock ブレーク受信確認を必要とすることです。この場合、oplock ブレーク通知はアドバイザリ専用であり、書き込みは受信確認なしで先に進むことができるため、FSCTL_REQUEST_OPLOCK は行われません。詳細については、「破壊的オプロックを参照してください。

ファイルが重複しない (同期) モードで開かれている場合、FSCTL_REQUEST_OPLOCK コントロールコードは失敗します。

この操作での重複した I/O の影響については、「DeviceIoControl」トピックの「解説」セクションを参照してください。

Windows 8 および Windows Server 2012 では、このコードは次のテクノロジでサポートされています。

テクノロジー	サポート
サーバーメッセージブロック (SMB) 3.0 プロトコル	いいえ
SMB 3.0 透過的フェールオーバー (TFO)	いいえ
SMB 3.0 とスケールアウトファイル共有 (SO)	いいえ
クラスター共有ボリュームファイルシステム (CsvFS)	はい
回復性のあるファイルシステム (ReFS)	はい

また、Windows 8 および Windows Server 2012 以降では、FSCTL_REQUEST_OPLOCK コントロールコードを使用して、ディレクトリとファイルの oplock を要求できます。ディレクトリの oplock 要求では、RequestedOplockLevel メンバーに OPLOCK_LEVEL_CACHE_READ または OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE を指定できます。

ディレクトリの列挙体の内容が変更されると、ディレクトリの R または RH oplock が None に切断されます。たとえば、ディレクトリ内のファイルの追加/削除、ディレクトリ内のファイルのサイズの変更、ディレクトリ内のファイルのタイムスタンプの変更などはすべて、ディレクトリの oplock を中断します。この oplock ブレークでは、ディレクトリ内の変更が発生する前に受信確認は必要ありません。これはアドバイザリ専用です。

ディレクトリ自体の名前が変更または削除されると、ディレクトリの RH oplock が R に中断されます。この oplock の中断には、ディレクトリへの変更が発生する前に受信確認が必要です。

必要条件

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

次の方法で共有

FSCTL_REQUEST_OPLOCK IOCTL (winioctl.h)

備考

必要条件

関連項目

フィードバック

その他のリソース