NtDeviceIoControlFile 関数 (ntifs.h)
ZwDeviceIoControlFile ルーチンは、指定したデバイス ドライバーにコントロール コードを直接送信し、対応するドライバーが指定した操作を実行します。
構文
__kernel_entry NTSYSCALLAPI NTSTATUS NtDeviceIoControlFile(
[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 用にファイル オブジェクトが開かれている必要があります。 基になる大容量記憶装置への 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_基本的な デバイス ドライバーによって、どのデバイス I/O 制御操作を実行するかを示すXxx コード。 このパラメーターの値は、 InputBuffer と OutputBuffer の形式と必要な長さ、および次のパラメーター ペアのうちどれが必要かを決定します。 システム定義のデバイスタイプ固有のIOCTL_Xxx コードの詳細については、Microsoft Windows Driver Kit (WDK) ドキュメントおよびデバイス入出力制御コードのデバイス テクノロジ固有のセクションを参照してください。
[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 値の定義については、「 I/O コントロール コード と デバイス入出力制御コードの使用」を参照してください。
呼び出し元が非同期 I/O 用にファイルを開いた場合 (FILE_SYNCHRONOUS_Xxx create/open オプションが設定されていません)、指定されたイベントがある場合は、デバイス制御操作の完了時にシグナル状態に設定されます。 それ以外の場合、 FileHandle で指定されたファイル オブジェクトはシグナル状態に設定されます。 ApcRoutine が指定された場合は、ApcContext ポインターと IoStatusBlock ポインターを使用して呼び出されます。
ミニフィルターでは、 ZwDeviceIoControlFile の代わりに FltDeviceIoControlFile を使用する必要があります。
ZwDeviceIoControlFile の呼び出し元は、IRQL = PASSIVE_LEVEL で実行され、特殊なカーネル APC が有効になっている必要があります。
ZwDeviceIoControlFile 関数の呼び出しがユーザー モードで行われる場合は、"ZwDeviceIoControlFile" ではなく "NtDeviceIoControlFile" という名前を使用する必要があります。
カーネル モード ドライバーからの呼び出しの場合、Windows ネイティブ システム サービス ルーチンの NtXxx および ZwXxx バージョンは、入力パラメーターを処理および解釈する方法で動作が異なる場合があります。 ルーチンの NtXxx バージョンと ZwXxx バージョンの間の関係の詳細については、「ネイティブ システム サービス ルーチンの Nt バージョンと Zw バージョンの使用」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 2000 |
| 対象プラットフォーム | ユニバーサル |
| Header | ntifs.h (Ntifs.h、Ntddk.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (「解説」セクションを参照) |
| DDI コンプライアンス規則 | HwStorPortProhibitedDDIs、PowerIrpDDis |