WdfDeviceEnqueueRequest 函式 (wdfdevice.h)

  • 發行項

[僅適用於 KMDF]

WdfDeviceEnqueueRequest 方法會將指定的 I/O 要求傳遞給架構，讓架構後續可以將要求新增至驅動程式為指定裝置所建立的其中一個 I/O 佇列。

語法

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

參數

[in] Device

架構裝置物件的句柄。

[in] Request

架構要求物件的句柄。

傳回值

如果作業成功，方法會傳回STATUS_SUCCESS。 其他傳回值包括：

傳回碼 Description
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，然後在呼叫 WdfDeviceEnqueueRequest 之後呼叫 WdfObjectDereference。 驅動程式必須在結束 EvtIoInCallerContext 之前取值要求。

如需 WdfDeviceEnqueueRequest 方法的詳細資訊，請參閱 管理 I/O 佇列。

對於 KMDF 1.0 和 1.5 版，必須在 PASSIVE_LEVEL呼叫 WdfDeviceEnqueueRequest 。 針對 1.7 版和更新版本，可以在 IRQL <= DISPATCH_LEVEL呼叫 WdfDeviceEnqueueRequest。

範例

下列程式代碼範例是 EvtIoInCallerContext 回呼函式，可尋找包含自定義 I/O 控制程式程式代碼的要求，IOCTL_NONPNP_METHOD_NEITHER。 如果找不到 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;
}

規格需求

需求 值
目標平台 Universal
最小 KMDF 版本 1.0
標頭 wdfdevice.h (包含 Wdf.h)
程式庫 Wdf01000.sys (請參閱 Framework Library Versioning.)
IRQL <= DISPATCH_LEVEL (請參閱備註一節)
DDI 合規性規則 DeferredRequestCompleted (kmdf) ， DriverCreate (kmdf ) ， KmdfIrql (kmdf) ， KmdfIrql2 () ， KmdfIrqlExplicit (kmdf) ， RequestCompleted (kmdf) 、RequestCompletedLocal (kmdf)

另請參閱

WDF_REQUEST_PARAMETERS_INIT

WdfRequestComplete

WdfRequestGetParameters