WdfIoQueueCreate 函式 (wdfio.h)

發行項
02/27/2024

[適用於 KMDF 和 UMDF]

WdfIoQueueCreate 方法會建立及設定指定裝置的 I/O 佇列。

語法

NTSTATUS WdfIoQueueCreate(
  [in]            WDFDEVICE              Device,
  [in]            PWDF_IO_QUEUE_CONFIG   Config,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES QueueAttributes,
  [out, optional] WDFQUEUE               *Queue
);

參數

[in] Device

與佇列相關聯之架構裝置物件的句柄。

[in] Config

呼叫端配置 WDF_IO_QUEUE_CONFIG 結構的指標。

[in, optional] QueueAttributes

呼叫端配置的 WDF_OBJECT_ATTRIBUTES 結構的指標，指定新對象的物件屬性。這個參數是選擇性的，而且可以WDF_NO_OBJECT_ATTRIBUTES。

[out, optional] Queue

接收架構佇列物件句柄之位置的指標。

傳回值

如果作業成功，WdfIoQueueCreate 會傳回STATUS_SUCCESS。否則，這個方法可能會傳回下列其中一個值：

傳回碼	Description
STATUS_INVALID_PARAMETER	輸入參數無效。
STATUS_INFO_LENGTH_MISMATCH	WDF_IO_QUEUE_CONFIG結構的大小不正確。
STATUS_POWER_STATE_INVALID	架構正在執行電源管理作業。
STATUS_INSUFFICIENT_RESOURCES	可用的記憶體數量太低。
STATUS_WDF_NO_CALLBACK	WDF_IO_QUEUE_CONFIG結構不會指定任何要求處理程式，而且分派方法不是 WdfIoQueueDispatchManual。
STATUS_UNSUCCESSFUL	驅動程式嘗試在裝置已有預設佇列時建立預設佇列，或發生內部錯誤。

這個方法也可能傳回其他 NTSTATUS值。

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

備註

對 WdfIoQueueCreate 的每個呼叫都會為裝置建立 I/O 佇列。您的驅動程式可以為每個裝置建立多個 I/O 佇列。

Config 和 QueueAttributes 參數會指定佇列的組態和物件屬性。

根據預設， Device 參數指定的架構裝置物件會成為新架構佇列物件的父物件。如果驅動程式在 WDF_OBJECT_ATTRIBUTES 結構的 ParentObject 成員中指定父物件，則父物件可以是架構裝置物件，或是父系鏈結導致架構裝置物件的任何物件。架構會在刪除父物件時刪除佇列物件。

如果您的驅動程式為架構佇列物件提供 EvtCleanupCallback 或 EvtDestroyCallback 回呼函式，則架構會在 IRQL = PASSIVE_LEVEL呼叫這些回呼函式。

如需 WdfIoQueueCreate 的詳細資訊，請參閱建立 I/O 佇列。

範例

下列程式代碼範例是 EvtDriverDeviceAdd 回呼函式的區段，該函式會建立裝置的預設 I/O 佇列。此範例會初始化 WDF_IO_QUEUE_CONFIG 結構，然後呼叫 WdfIoQueueCreate。

NTSTATUS
MyEvtDriverDeviceAdd(
    IN WDFDRIVER  Driver,
    IN PWDFDEVICE_INIT  DeviceInit
    )
{
    WDF_IO_QUEUE_CONFIG  ioQueueConfig;
    WDFQUEUE  hQueue;
...
    WDF_IO_QUEUE_CONFIG_INIT_DEFAULT_QUEUE(
                                           &ioQueueConfig,
                                           WdfIoQueueDispatchSequential
                                           );

    ioQueueConfig.EvtIoDefault = MyEvtIoDefault;

    status = WdfIoQueueCreate(
                              device,
                              &ioQueueConfig,
                              WDF_NO_OBJECT_ATTRIBUTES,
                              &hQueue
                              );
    if (!NT_SUCCESS (status)) {
        return status;
    }
...
}

規格需求

需求	值
目標平台	Universal
最低 KMDF 版本	1.0
最低UMDF版本	2.0
標頭	wdfio.h (包含 Wdf.h)
程式庫	Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
DDI 合規性規則	ChangeQueueState (kmdf) ， DriverCreate (kmdf) ， DrvAckIoStop (kmdf ) ， KmdfIrql (kmdf ) ， KmdfIrql2 (kmdf) ， KmdfIrqlExplicit (kmdf)