ZwFsControlFile 関数 (ntifs.h)
ZwFsControlFile ルーチンは、指定したファイル システムまたはファイル システム フィルター ドライバーにコントロール コードを直接送信し、対応するドライバーが指定したアクションを実行します。
構文
NTSYSAPI NTSTATUS ZwFsControlFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] ULONG FsControlCode,
[in, optional] PVOID InputBuffer,
[in] ULONG InputBufferLength,
[out, optional] PVOID OutputBuffer,
[in] ULONG OutputBufferLength
);
パラメーター
[in] FileHandle
指定したアクションを実行するファイルまたはディレクトリを表すファイル オブジェクトの ZwCreateFile または ZwOpenFile によって返されるハンドル。 呼び出し元が Event、ApcRoutine、APC コンテキスト (ApcContext の場合)、または完了コンテキスト (ApcContext 内) を指定している場合は、非同期 I/O 用にファイル オブジェクトを開く必要があります。
[in, optional] Event
呼び出し元によって作成されたイベントのハンドル。 このパラメーターを指定すると、要求された操作が完了し、指定されたイベントが Signaled 状態に設定されるまで、呼び出し元は待機状態になります。 このパラメーターは省略可能であり、 NULL にすることができます。 呼び出し元が FileHandle が Signaled 状態に設定されるのを待機する場合は NULL にする必要があります。
[in, optional] ApcRoutine
要求された操作が完了したときに呼び出される呼び出し元が指定した APC ルーチンのアドレス。 このパラメーターは省略可能であり、 NULL にすることができます。 ファイル オブジェクトに関連付けられている I/O 入力候補オブジェクトがある場合は NULL にする必要があります。
[in, optional] ApcContext
呼び出し元によって決定されたコンテキスト領域へのポインター。 このパラメーター値は、呼び出し元が APC を提供する場合は APC コンテキストとして使用され、I/O 完了オブジェクトがファイル オブジェクトに関連付けられている場合は完了コンテキストとして使用されます。 操作が完了すると、APC コンテキストが指定されている場合は APC に渡されるか、I/O マネージャーが関連付けられた I/O 完了オブジェクトに投稿する完了メッセージの一部として完了コンテキストが含まれます。
このパラメーターは省略可能であり、 NULL にすることができます。 ApcRoutine が NULL で、ファイル オブジェクトに関連付けられている I/O 完了オブジェクトがない場合は NULL にする必要があります。
[out] IoStatusBlock
最終的な完了状態と操作に関する情報を受け取るIO_STATUS_BLOCK構造体へのポインター。 データを返す呼び出しが成功した場合、 OutputBuffer に書き込まれたバイト数は、この構造体の Information メンバーで返されます。
[in] FsControlCode
実行するファイル システム制御操作を示すFSCTL_XXX コード。このパラメーターの値は、 InputBuffer と OutputBuffer の形式と必要な長さ、および必要な次のパラメーター ペアを決定します。 システム定義のFSCTL_XXX コードの詳細については、Microsoft Windows SDKドキュメントの DeviceIoControl のリファレンス エントリの「解説」セクションを参照してください。
[in, optional] InputBuffer
ターゲット ドライバーに提供されるデバイス固有の情報を含む呼び出し元によって割り当てられた入力バッファーへのポインター。 FsControlCode で入力データを必要としない操作が指定されている場合、このポインターは省略可能であり、NULL にすることができます。
[in] InputBufferLength
InputBuffer のバッファーのサイズ (バイト単位)。 InputBuffer が NULL の場合、この値は無視されます。
[out, optional] OutputBuffer
ターゲット ドライバーから情報が返される呼び出し元によって割り当てられた出力バッファーへのポインター。 FsControlCode で出力データを生成しない操作が指定されている場合、このポインターは省略可能であり、NULL にすることができます。
[in] OutputBufferLength
OutputBuffer のバッファーのサイズ (バイト単位)。 OutputBuffer が NULL の場合、この値は無視されます。
戻り値
ZwFsControlFile は 、次のいずれかのSTATUS_SUCCESSまたは適切な NTSTATUS 値を返します。
注釈
ZwFsControlFile は、システムおよびカーネル モード ドライバーに対する入力データと出力データの一貫性のあるビューを提供しながら、通信インターフェイスを指定するドライバーに依存するメソッドをアプリケーションと基になるドライバーに提供します。
呼び出し元が非同期 I/O 用にファイルを開いた場合 (どちらもFILE_SYNCHRONOUS_XXX create/open オプションが設定されていません)、指定されたイベントがある場合は、デバイス制御操作の完了時にシグナル状態に設定されます。 それ以外の場合、 FileHandle で指定されたファイル オブジェクトはシグナル状態に設定されます。 ApcRoutine が指定されている場合は、ApcContext ポインターと IoStatusBlock ポインターを使用して呼び出されます。
現在、カーネル モード ドライバーについては、次の FSCTL コードが文書化されています。
FSCTL_OPBATCH_ACK_CLOSE_PENDING
FSCTL_OPLOCK_BREAK_ACKNOWLEDGE
システム定義FSCTL_XXX コードの詳細については、Microsoft Windows SDK ドキュメントの DeviceIoControl のリファレンス エントリの「解説」セクションを参照してください。
システム定義のIOCTL_XXX コード、およびドライバー固有のIOCTL_XXX 値またはFSCTL_XXX 値の定義の詳細については、Windows SDK ドキュメントの「カーネル モード アーキテクチャ ガイド」および「デバイス入出力制御コード」の「I/O コントロール コードの使用」を参照してください。
ミニフィルターでは、 ZwFsControlFile の代わりに FltFsControlFile を使用する必要があります。
ZwFsControlFile の呼び出し元は、IRQL = PASSIVE_LEVEL で実行され、特殊なカーネル API が有効になっている必要があります。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 2000。 |
| 対象プラットフォーム | ユニバーサル |
| Header | ntifs.h (Ntifs.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (「解説」セクションを参照) |
| DDI コンプライアンス規則 | HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm) |