WdfIoQueueCreate 函式（wdfio.h）

發行項
03/22/2025

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

回傳碼	說明
STATUS_INVALID_PARAMETER	輸入參數無效。
STATUS_INFO_LENGTH_MISMATCH	WDF_IO_QUEUE_CONFIG 結構的大小不正確。
STATUS_POWER_STATE_INVALID	架構正在執行電源管理作業。
資源不足狀態	可用的記憶體數量太低。
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 framework 佇列物件的回呼函式，架構會在 IRQL = PASSIVE_LEVEL 呼叫這些回呼函式。

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

範例

下列程式代碼範例是建立裝置預設 I/O 佇列的 EvtDriverDeviceAdd 回呼函式的區段。此範例會初始化 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;
    }
...
}

需求

要求	價值
目標平臺	普遍
最低 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）