ZwDeviceIoControlFile 関数 (ntddk.h)
ZwDeviceIoControlFile ルーチンは、コントロール コードを指定したデバイス ドライバーに直接送信し、対応するドライバーが指定した操作を実行します。
構文
NTSYSAPI NTSTATUS ZwDeviceIoControlFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] ULONG IoControlCode,
[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 用にファイル オブジェクトを開く必要があります。 基になる大容量記憶装置への入出力の場合は、ストレージ・デバイス (DASD) への直接アクセス用にファイル・オブジェクトがオープンされている必要があります。
[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
最終的な完了状態と操作に関する情報を受け取る変数へのポインター。 データを返す呼び出しが成功すると、 OutputBuffer に書き込まれたバイト数が Information メンバーに返されます。
[in] IoControlCode
IOCTL_XXX コード。通常は基になるデバイス ドライバーによって実行されるデバイス I/O 制御操作を示します。 このパラメーターの値は、 InputBuffer と OutputBuffer の形式と必要な長さ、および必要な次のパラメーター ペアを決定します。 システム定義のデバイスの種類固有のIOCTL_XXX コードの詳細については、Microsoft Windows Driver Kit (WDK) ドキュメントのデバイス テクノロジ固有のセクションと、Microsoft Windows SDKドキュメントの「デバイスの入出力制御コード」を参照してください。
[in, optional] InputBuffer
ターゲット デバイスに与えられるデバイス固有の情報を含む呼び出し元によって割り当てられた入力バッファーへのポインター。 IoControlCode で入力データを必要としない操作が指定されている場合、このポインターは NULL にすることができます。
[in] InputBufferLength
InputBuffer のバッファーのサイズ (バイト単位)。 InputBuffer が NULL の場合は、InputBufferLength を 0 に設定します。
[out, optional] OutputBuffer
ターゲット デバイスから情報が返される呼び出し元によって割り当てられた出力バッファーへのポインター。 IoControlCode で出力データを生成しない操作が指定されている場合、このポインターは NULL にすることができます。
[in] OutputBufferLength
OutputBuffer のバッファーのサイズ (バイト単位)。 OutputBuffer が NULL の場合は、OutputBufferLength を 0 に設定します。
戻り値
基になるドライバーが要求された操作を正常に実行した場合、ZwDeviceIoControlFile はSTATUS_SUCCESSを返します。 それ以外の場合、戻り値は、基になるドライバーから伝達されるエラー状態コードである可能性があります。 考えられるエラー状態コードは次のとおりです。
注釈
ZwDeviceIoControlFile は、システムとカーネル モード ドライバーに対する入力データと出力データの一貫性のあるビューを提供し、アプリケーションと基になるドライバーに、通信インターフェイスを指定するデバイスに依存するメソッドを提供します。
システム定義IOCTL_XXX コードの詳細、およびドライバー固有のIOCTL_XXX 値またはFSCTL_XXX 値の定義については、Microsoft Windows SDK ドキュメントの「カーネル モード アーキテクチャ ガイド」および「デバイス入出力制御コード」の「I/O コントロール コードの使用」を参照してください。
呼び出し元が非同期 I/O 用にファイルを開いた場合 (どちらもFILE_SYNCHRONOUS_XXX create/open オプションが設定されていません)、指定されたイベントがある場合は、デバイス制御操作の完了時にシグナル状態に設定されます。 それ以外の場合、 FileHandle で指定されたファイル オブジェクトはシグナル状態に設定されます。 ApcRoutine が指定されている場合は、ApcContext ポインターと IoStatusBlock ポインターを使用して呼び出されます。
ミニフィルターでは、 ZwDeviceIoControlFile の代わりに FltDeviceIoControlFile を使用する必要があります。
ZwDeviceIoControlFile の呼び出し元は、IRQL = PASSIVE_LEVEL で実行され、特殊なカーネル API が有効になっている必要があります。
ZwDeviceIoControlFile 関数の呼び出しがユーザー モードで行われる場合は、"ZwDeviceIoControlFile" ではなく"NtDeviceIoControlFile" という名前を使用する必要があります。
カーネル モード ドライバーからの呼び出しの場合、Windows ネイティブ システム サービス ルーチンの NtXxx および ZwXxx バージョンは、入力パラメーターを処理および解釈する方法で動作が異なります。 ルーチンの NtXxx バージョンと ZwXxx バージョン間の関係の詳細については、「Using Nt and Zw Versions of the Native System Services Routines」を参照してください。
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | ユニバーサル |
| Header | ntddk.h (Ntifs.h、Ntddk.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (「解説」セクションを参照) |
| DDI コンプライアンス規則 | HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm) |