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 コントロール コードのバッファーの説明」を参照してください。

要件

こちらもご覧ください

IO_STACK_LOCATION

IRP

IoAllocateIrp

IoBuildAsynchronousFsdRequest

IoBuildSynchronousFsdRequest

IoCallDriver

IoCompleteRequest

KeInitializeEvent

KeWaitForSingleObject