ZwDeviceIoControlFile 関数 (ntifs.h)

[アーティクル]
12/21/2024

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 によって返されるハンドルは、コントロール情報を指定する必要があるデバイスを表すファイルオブジェクトの ZwOpenFile、または情報を返す必要があります。呼び出し元が イベント、ApcRoutine、APC コンテキスト (ApcContext)、または完了コンテキスト (ApcContext内) を指定する場合は、非同期 I/O 用にファイルオブジェクトを開く必要があります。基になる大容量記憶装置に対する I/O の場合、ストレージデバイス (BLOB) への直接アクセス用にファイルオブジェクトが開かれている必要があります。

[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 ドキュメントの「カーネルモードアーキテクチャガイドおよび Device Input and Output Control Codes の I/O 制御コードの使用」を参照してください。

呼び出し元が非同期 I/O 用にファイルを開いた場合 (XXX FILE_SYNCHRONOUS_ 作成/開くオプションがどちらも設定されていません)、指定されたイベントがある場合は、デバイス制御操作の完了時にシグナル状態に設定されます。それ以外の場合は、FileHandle で指定ファイルオブジェクトがシグナル状態に設定されます。 ApcRoutine が指定された場合は、ApcContext を使用して呼び出され、IoStatusBlock ポインターがされます。

ミニフィルターでは、ZwDeviceIoControlFileではなく、FltDeviceIoControlFile 使用する必要があります。

ZwDeviceIoControlFile の呼び出し元は、IRQL = PASSIVE_LEVEL で実行され、特殊なカーネル APCs が有効になっている必要があります。

注ZwDeviceIoControlFile 関数の呼び出しがユーザーモードで発生する場合は、"ZwDeviceIoControlFile" ではなく"NtDeviceIoControlFile" という名前を使用する必要があります。

カーネルモードドライバーからの呼び出しの場合、Windows ネイティブシステムサービスルーチンの **Nt*Xxx*** バージョンと **Zw*Xxx*** バージョンは、入力パラメーターを処理して解釈する方法で動作が異なる場合があります。ルーチンの **Nt*Xxx*** バージョンと **Zw*Xxx*** バージョン間の関係の詳細については、「ネイティブシステムサービスルーチンの Nt バージョンと Zw バージョンの使用](/windows-hardware/drivers/kernel/using-nt-and-zw-versions-of-the-native-system-services-routines)を参照してください。

必要条件

要件	価値
サポートされる最小クライアント	Windows 2000。
ターゲットプラットフォームの	万国
ヘッダー	ntifs.h (Ntifs.h、Ntddk.h を含む)
ライブラリ	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (「解説」セクションを参照)
DDI コンプライアンス規則をする	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)

次の方法で共有

ZwDeviceIoControlFile 関数 (ntifs.h)

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース