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を返します。それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。

リターンコード	説明
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 キューの作成」を参照してください。

例

次のコード例は、デバイスの既定の 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
Header	wdfio.h (Wdf.h を含む)
Library	Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
DDI コンプライアンス規則	ChangeQueueState(kmdf), DriverCreate(kmdf), DrvAckIoStop(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)