WdfRequestForwardToIoQueue 函式（wdfrequest.h）

發行項
02/07/2025

[適用於 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，則必須先呼叫 WdfRequestUnmarkCancelable，再呼叫 WdfRequestForwardToIoQueue。

在驅動程式呼叫 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
標頭	wdfrequest.h （包括 Wdf.h）
連結庫	Wdf01000.sys （KMDF）：WUDFx02000.dll （UMDF）
IRQL	<=DISPATCH_LEVEL
DDI 合規性規則	DeferredRequestCompleted（kmdf），DriverCreate（kmdf），InvalidReqAccess（kmdf），InvalidReqAccessLocal，KmdfIrql（kmdf），KmdfIrql2（kmdf），KmdfIrqlExplicit（kmdf），RequestCompleted（kmdf），RequestCompletedLocal（kmdf）