WdfRequestForwardToIoQueue 関数 (wdfrequest.h)

[アーティクル]
02/27/2024

[KMDF と UMDF に適用]

WdfRequestForwardToIoQueue メソッドは、呼び出し元ドライバーの I/O キューのいずれかに I/O 要求を再キューします。

構文

NTSTATUS WdfRequestForwardToIoQueue(
  [in] WDFREQUEST Request,
  [in] WDFQUEUE   DestinationQueue
);

パラメーター

[in] Request

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

[in] DestinationQueue

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

戻り値

操作が成功した場合、WdfRequestForwardToIoQueue はSTATUS_SUCCESSを返します。それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。

リターンコード	説明
STATUS_INVALID_DEVICE_REQUEST	この値は、次のいずれかが発生した場合に返されます。ドライバーが I/O キューから要求を取得しませんでした。ソースキューと宛先キューは同じです。ソースキューと宛先キューは同じデバイスに属していません。ドライバーは要求を所有していません。要求は取り消し可能です。
STATUS_WDF_BUSY	宛先キューが新しい要求を受け入れていません。

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

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

注釈

ドライバーは I/O 要求を所有している必要があり、その I/O キューのいずれかから要求を取得している必要があります。

ソースキューと宛先キューを同じにすることはできません。言い換えると、ドライバーは WdfRequestForwardToIoQueue を呼び出して、元のキューに要求を返すことはできません。同じキューに要求を再キューするには、 WdfRequestRequeue を使用します。

ソースキューと宛先キューの両方が同じデバイスに属している必要があります。

要求を取り消し可能にすることはできません。ドライバーが WdfRequestMarkCancelable または WdfRequestMarkCancelableEx を呼び出して要求を取り消し可能にした場合は、WdfRequestForwardToIoQueue を呼び出す前に WdfRequestUnmarkCancelable を呼び出す必要があります。

ドライバーが WdfRequestForwardToIoQueue を呼び出した後、フレームワークが新しいキューからドライバーに要求を配信するまで、ドライバーは再キューされた要求を所有しません。要求が新しいキューにある間、フレームワークは要求を所有し、ドライバーに通知せずに要求を取り消すことができます。

WdfRequestForwardToIoQueue が返される前に、次のイベントが発生する可能性があります。

宛先キューが空の場合、フレームワークは再キュー化された I/O 要求を宛先キューの要求ハンドラーのいずれかに配信できます。
ソースキューのディスパッチメソッドが順次または並列の場合、フレームワークはソースキューの要求ハンドラーのいずれかに別の要求を配信できます。

WdfRequestForwardToIoQueue の詳細については、「I/O 要求のキューの再キュー化」および「I/O キューの管理」を参照してください。

例

次のコード例は、PCIDRV サンプルドライバーからの EvtIoDeviceControl コールバック関数です。受信した要求に IOCTL_NDISPROT_INDICATE_STATUS の I/O 制御コードが含まれている場合、ドライバーは WdfRequestForwardToIoQueue を呼び出して、要求を別の I/O キューに移動します。

VOID
PciDrvEvtIoDeviceControl(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  OutputBufferLength,
    IN size_t  InputBufferLength,
    IN ULONG  IoControlCode
    )
{
    NTSTATUS  status= STATUS_SUCCESS;
    PFDO_DATA  fdoData = NULL;
    WDFDEVICE  hDevice;
    WDF_REQUEST_PARAMETERS  params;

    UNREFERENCED_PARAMETER(OutputBufferLength);
    UNREFERENCED_PARAMETER(InputBufferLength);

    hDevice = WdfIoQueueGetDevice(Queue);
    fdoData = FdoGetData(hDevice);

    WDF_REQUEST_PARAMETERS_INIT(&params);
    WdfRequestGetParameters(
                            Request,
                            &params
                            );

    switch (IoControlCode)
    {
        case IOCTL_NDISPROT_QUERY_OID_VALUE:
            NICHandleQueryOidRequest(
                                     Queue,
                                     Request,
                                     &params
                                     );
            break;

        case IOCTL_NDISPROT_SET_OID_VALUE:
            NICHandleSetOidRequest(
                                   Queue,
                                   Request,
                                   &params
                                   );
            break;

        case IOCTL_NDISPROT_INDICATE_STATUS:
            status = WdfRequestForwardToIoQueue(
                                                Request,
                                                fdoData->PendingIoctlQueue
                                                );
            if(!NT_SUCCESS(status)){
                WdfRequestComplete(
                                   Request,
                                   status
                                   );
                break;
            }
            break;

        default:
            WdfRequestComplete(
                               Request,
                               STATUS_INVALID_DEVICE_REQUEST
                               );
            break;
    }
    return;
}

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
最小 UMDF バージョン	2.0
Header	wdfrequest.h (Wdf.h を含む)
Library	Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI コンプライアンス規則	DeferredRequestCompleted(kmdf)、DriverCreate(kmdf)、InvalidReqAccess(kmdf)、InvalidReqAccessLocal(kmdf)、KmdfIrql(kmdf)、KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)、RequestCompleted(kmdf)、RequestCompletedLocal (kmdf)