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。否則，這個方法可能會傳回下列其中一個值：

傳回碼	Description
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;
}

規格需求

需求	值
目標平台	Universal
最低 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 () kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、KmdfIrqlExplicit (kmdf) 、 RequestCompleted (kmdf) 、 RequestCompletedLocal (kmdf)