IoBuildDeviceIoControlRequest 関数 (wdm.h)
IoBuildDeviceIoControlRequest ルーチンは、同期的に処理されたデバイス制御要求に対して IRP を割り当てて設定します。
構文
__drv_aliasesMem PIRP IoBuildDeviceIoControlRequest(
[in] ULONG IoControlCode,
[in] PDEVICE_OBJECT DeviceObject,
[in, optional] PVOID InputBuffer,
[in] ULONG InputBufferLength,
[out, optional] PVOID OutputBuffer,
[in] ULONG OutputBufferLength,
[in] BOOLEAN InternalDeviceIoControl,
[in, optional] PKEVENT Event,
[out] PIO_STATUS_BLOCK IoStatusBlock
);
パラメーター
[in] IoControlCode
要求で使用する I/O 制御コード (IOCTL) を提供します。 デバイスの種類固有の I/O コントロール コードの詳細については、Windows Driver Kit (WDK) の「デバイスの種類固有のセクション」を参照してください。
[in] DeviceObject
ターゲット デバイスを表す、次の下位ドライバーのデバイス オブジェクトの DEVICE_OBJECT 構造体へのポインターを提供します。
[in, optional] InputBuffer
下位ドライバーに渡される入力バッファーへのポインターを提供します。要求が下位ドライバーに入力データを渡さない場合は NULL を指定します。
[in] InputBufferLength
入力バッファーの長さをバイト単位で指定します。 InputBuffer が NULL の場合、InputBufferLength は 0 である必要があります。
[out, optional] OutputBuffer
下位ドライバーがデータを返す出力バッファーへのポインターを提供します。要求がデータを返すために下位ドライバーを必要としない場合は NULL です。
[in] OutputBufferLength
出力バッファーの長さをバイト単位で指定します。 OutputBuffer が NULL の場合、OutputBufferLength は 0 である必要があります。
[in] InternalDeviceIoControl
TRUE の場合、ルーチンは IRP の主要な関数コードをIRP_MJ_INTERNAL_DEVICE_CONTROLに設定します。 それ以外の場合、ルーチンは IRP の主要な関数コードを IRP_MJ_DEVICE_CONTROLに設定します。
[in, optional] Event
呼び出し元によって割り当てられ、初期化されたイベント オブジェクトへのポインターを提供します。 I/O マネージャーは、下位レベルのドライバーが要求された操作を完了すると、イベントを Signaled 状態に設定します。 IoCallDriver を呼び出した後、ドライバーはイベント オブジェクトを待機できます。 Event パラメーターは省略可能であり、NULL に設定できます。 ただし、 Event が NULL の場合、呼び出し元は、操作の完了時に呼び出し元に通知する IRP の IoCompletion ルーチンを指定する必要があります。
[out] IoStatusBlock
下位ドライバーによって要求が完了したときに設定される I/O 状態ブロックを指定します。
戻り値
操作が成功すると、 IoBuildDeviceIoControlRequest は IRP へのポインターを返し、指定されたパラメーターから次の下位ドライバーの I/O スタックの場所が設定されます。 それ以外の場合、ルーチンは NULL を返します。
注釈
ドライバーは IoBuildDeviceIoControlRequest を呼び出して、下位レベルのドライバーに同期的に送信するデバイス制御要求の IRP を設定できます。
IoBuildDeviceIoControlRequest を呼び出して要求を作成した後、ドライバーは IoCallDriver を呼び出して次の下位ドライバーに要求を送信する必要があります。 IoCallDriver がSTATUS_PENDINGを返す場合、ドライバーは、指定されたイベントで KeWaitForSingleObject を呼び出すことによって、IRP の完了を待機する必要があります。 ほとんどのドライバーは、IRP の IoCompletion ルーチンを設定する必要はありません。
IoBuildDeviceIoControlRequest によって作成された IRP は、ドライバーによる IoCompleteRequest の呼び出しによって完了する必要があります。 IoBuildDeviceIoControlRequest を呼び出すドライバーは、IoCompleteRequest が呼び出された後に I/O マネージャーによってこれらの同期 IRP が解放されるため、IoFreeIrp を呼び出してはなりません。
IoBuildDeviceIoControlRequest は、現在のスレッドに固有の IRP キューに作成する IRP をキューに入れます。 スレッドが終了すると、I/O マネージャーは IRP を取り消します。
呼び出し元が InputBuffer パラメーターまたは OutputBuffer パラメーターを 指定する場合、このパラメーターはシステム メモリに存在するバッファーを指す必要があります。 呼び出し元は、ユーザー モード バッファーから入力バッファーにコピーするすべてのパラメーター値を検証する必要があります。 入力バッファーには、要求の発信元がユーザー モード アプリケーションかカーネル モード ドライバーかに応じて、異なる方法で解釈されるパラメーター値が含まれる場合があります。 IoBuildDeviceIoControlRequest が返す IRP では、RequestorMode フィールドは常に KernelMode に設定されます。 この値は、要求と要求に含まれるすべての情報が、信頼されたカーネル モード コンポーネントからの情報であることを示します。
呼び出し元がユーザー モード バッファーから入力バッファーにコピーするパラメーター値を検証できない場合、またはこれらの値をカーネル モード コンポーネントからの値として解釈しない場合、呼び出し元は IRP の RequestorMode フィールドを UserMode に設定する必要があります。 この設定は、バッファーに信頼されていないユーザー モード データが含まれていることを I/O コントロール要求を処理するドライバーに通知します。
InputBuffer パラメーターと OutputBuffer パラメーターの内容が IRP に格納される実際のメソッドは、IOCTL の TransferType 値によって異なります。 この値の詳細については、「 I/O コントロール コードのバッファーの説明」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 2000 以降で使用できます。 |
| 対象プラットフォーム | ユニバーサル |
| Header | wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | <= APC_LEVEL |
| DDI コンプライアンス規則 | HwStorPortProhibitedDDIs(storport), IoAllocateIrpSignalEventInCompletion(wdm), IoAllocateIrpSignalEventInCompletion2(wdm)、 IoAllocateIrpSignalEventInCompletion3(wdm)、 IoBuildDeviceControlNoFree(wdm)、 IoBuildDeviceControlWait(wdm)、 IoBuildDeviceControlWaitTimeout(wdm)、 IoBuildDeviceIoControlSetEvent(wdm)、 IrqlIoPassive1(wdm)、 PowerIrpDDis(wdm)、、 SignalEventInCompletion(wdm) |
こちらもご覧ください
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示