WdfDeviceEnqueueRequest 関数 (wdfdevice.h)

  • [アーティクル]

[KMDF にのみ適用]

WdfDeviceEnqueueRequest メソッドは、指定した I/O 要求をフレームワークに配信し、その後、フレームワークが、指定したデバイスに対してドライバーが作成した I/O キューのいずれかに要求を追加できるようにします。

構文

NTSTATUS WdfDeviceEnqueueRequest(
  [in] WDFDEVICE  Device,
  [in] WDFREQUEST Request
);

パラメーター

[in] Device

フレームワーク デバイス オブジェクトへのハンドル。

[in] Request

フレームワーク要求オブジェクトへのハンドル。

戻り値

操作が成功した場合、メソッドは STATUS_SUCCESS を返します。 その他の戻り値は次のとおりです。

リターン コード 説明
STATUS_INSUFFICIENT_RESOURCES
 使用可能なメモリの量が少ない。
STATUS_INVALID_DEVICE_REQUEST
 ドライバーによってデバイスの I/O キューが作成されておらず、ドライバーはフィルター ドライバーではありません。
STATUS_WDF_BUSY
 デバイスの I/O キューが要求を受け入れていません。
 

メソッドは、他の NTSTATUS 値を返す場合があります。

ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。

注釈

ドライバーは、EvtIoInCallerContext コールバック関数からのみ WdfDeviceEnqueueRequest を呼び出すことができます。

WdfDeviceEnqueueRequest メソッドは、ドライバーが作成した場合、デバイスの要求の種類固有の I/O キューに要求を追加します。 それ以外の場合、 メソッドは、ドライバーが要求を作成した場合に、デバイスの既定のキューに要求を追加します。

ドライバーがデバイスの I/O キューを作成していない場合、 WdfDeviceEnqueueRequest は次の処理を行います。

  • ドライバーがフィルター ドライバーの場合、 WdfDeviceEnqueueRequest はドライバーの I/O ターゲットに要求を送信します。
  • ドライバーがフィルター ドライバーでない場合、 WdfDeviceEnqueueRequest はSTATUS_INVALID_DEVICE_REQUESTを返します。
WdfDeviceEnqueueRequest の実行中に、ドライバーが要求を受信して完了または取り消す可能性があります。

その結果、ドライバーが WdfDeviceEnqueueRequest を呼び出した後に要求またはそのコンテキストを使用する必要がある場合は、 WdfDeviceEnqueueRequest を呼び出す前に要求に対する参照を受け取る必要があります。

これを行うには、ドライバーは WdfDeviceEnqueueRequest の呼び出しの後に WdfObjectReference を呼び出してから、WdfObjectDereference を呼び出すことができます。 ドライバーは、EvtIoInCallerContext を終了する前に要求を逆参照する必要があります。

WdfDeviceEnqueueRequest メソッドの詳細については、「I/O キューの管理」を参照してください。

バージョン 1.0 および 1.5 の KMDF の場合、 WdfDeviceEnqueueRequest をPASSIVE_LEVELで呼び出す必要があります。 バージョン 1.7 以降では、IRQL <= DISPATCH_LEVEL で WdfDeviceEnqueueRequest を呼び出すことができます。

例

次のコード例は、カスタム I/O コントロール コード (IOCTL_NONPNP_METHOD_NEITHER) を含む要求を検索する EvtIoInCallerContext コールバック関数です。 I/O コントロール コードが見つからない場合、コールバック関数は要求をフレームワークに返すだけです。 コールバック関数は、I/O 制御コードを検出した場合、要求を前処理してフレームワークに返します。 エラーが発生した場合、コールバック関数は要求を完了します。

VOID
MyEvtDeviceIoInCallerContext(
    IN WDFDEVICE  Device,
    IN WDFREQUEST Request
    )
{
    NTSTATUS  status = STATUS_SUCCESS;
    WDF_REQUEST_PARAMETERS  params;

    WDF_REQUEST_PARAMETERS_INIT(&params);
    WdfRequestGetParameters(
                            Request,
                            &params
                            );
    if(!(params.Type == WdfRequestTypeDeviceControl &&
         params.Parameters.DeviceIoControl.IoControlCode == IOCTL_NONPNP_METHOD_NEITHER)) {
        status = WdfDeviceEnqueueRequest(
                                         Device,
                                         Request
                                         );
        if(!NT_SUCCESS(status)) {
            goto End;
        }
        return;
    }
    //
    // Found a match for the control code. Preprocess the request, and then
    // return the request to the framework.
    //

    //...(Preprocess the request here.)

    status = WdfDeviceEnqueueRequest(
                                     Device,
                                     Request
                                     );
    if(!NT_SUCCESS(status)) {
        goto End;
    }
    return;
End:
    WdfRequestComplete(
                       Request,
                       status
                       );
    return;
}

要件

要件 値
対象プラットフォーム ユニバーサル
最小 KMDF バージョン 1.0
Header wdfdevice.h (Wdf.h を含む)
Library Wdf01000.sys (「Framework ライブラリのバージョン管理」を参照)。
IRQL <= DISPATCH_LEVEL (「解説」セクションを参照)
DDI コンプライアンス規則 DeferredRequestCompleted(kmdf)、 DriverCreate(kmdf)、 KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)、 RequestCompleted(kmdf)、 RequestCompletedLocal(kmdf)

こちらもご覧ください

WDF_REQUEST_PARAMETERS_INIT

WdfRequestComplete

WdfRequestGetParameters