WdfIoQueueCreate 関数 (wdfio.h)

  • [アーティクル]

[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)

こちらもご覧ください

WDF_IO_QUEUE_CONFIG

WDF_IO_QUEUE_CONFIG_INIT_DEFAULT_QUEUE

WDF_OBJECT_ATTRIBUTES

WdfDeviceConfigureRequestDispatching

WdfRequestForwardToIoQueue