WdfIoQueueCreate-Funktion (wdfio.h)

Artikel
02/27/2024

[Gilt für KMDF und UMDF]

Die WdfIoQueueCreate-Methode erstellt und konfiguriert eine E/A-Warteschlange für ein angegebenes Gerät.

Syntax

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

Parameter

[in] Device

Ein Handle für das Frameworkgerätobjekt, dem die Warteschlange zugeordnet wird.

[in] Config

Ein Zeiger auf eine aufruferseitig zugewiesene WDF_IO_QUEUE_CONFIG-Struktur .

[in, optional] QueueAttributes

Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_OBJECT_ATTRIBUTES-Struktur , die Objektattribute für das neue Objekt angibt. Dieser Parameter ist optional und kann WDF_NO_OBJECT_ATTRIBUTES werden.

[out, optional] Queue

Ein Zeiger auf eine Position, die ein Handle für ein Framework-Warteschlangenobjekt empfängt.

Rückgabewert

WdfIoQueueCreate gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Methode möglicherweise einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Ein Eingabeparameter ist ungültig.
STATUS_INFO_LENGTH_MISMATCH	Die Größe der WDF_IO_QUEUE_CONFIG-Struktur ist falsch.
STATUS_POWER_STATE_INVALID	Das Framework führt einen Energieverwaltungsvorgang aus.
STATUS_INSUFFICIENT_RESOURCES	Der verfügbare Arbeitsspeicher ist zu gering.
STATUS_WDF_NO_CALLBACK	Die WDF_IO_QUEUE_CONFIG-Struktur gibt keine Anforderungshandler an, und die Dispatchingmethode ist nicht WdfIoQueueDispatchManual.
STATUS_UNSUCCESSFUL	Der Treiber versucht, eine Standardwarteschlange zu erstellen, während eine Standardwarteschlange für das Gerät bereits vorhanden ist, oder es ist ein interner Fehler aufgetreten.

Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.

Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.

Hinweise

Jeder Aufruf von WdfIoQueueCreate erstellt eine E/A-Warteschlange für ein Gerät. Ihr Treiber kann mehrere E/A-Warteschlangen für jedes Gerät erstellen.

Die Parameter Config und QueueAttributes geben die Konfigurations- und Objektattribute der Warteschlange an.

Standardmäßig wird das framework-Geräteobjekt, das der Device-Parameter angibt, das übergeordnete Objekt für das neue Framework-Warteschlangenobjekt. Wenn der Treiber ein übergeordnetes Objekt im ParentObject-Member der WDF_OBJECT_ATTRIBUTES-Struktur angibt, kann das übergeordnete Objekt ein Framework-Geräteobjekt oder ein beliebiges Objekt sein, dessen Kette von übergeordneten Elementen zu einem Framework-Geräteobjekt führt. Das Framework löscht das Warteschlangenobjekt, wenn es das übergeordnete Objekt löscht.

Wenn Ihr Treiber EvtCleanupCallback - oder EvtDestroyCallback-Rückruffunktionen für das Framework-Warteschlangenobjekt bereitstellt, ruft das Framework diese Rückruffunktionen unter IRQL = PASSIVE_LEVEL auf.

Weitere Informationen zu WdfIoQueueCreate finden Sie unter Erstellen von E/A-Warteschlangen.

Beispiele

Das folgende Codebeispiel ist der Abschnitt einer EvtDriverDeviceAdd-Rückruffunktion , die die Standard-E/A-Warteschlange eines Geräts erstellt. Das Beispiel initialisiert eine WDF_IO_QUEUE_CONFIG-Struktur und ruft dann WdfIoQueueCreate auf.

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;
    }
...
}

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfio.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
DDI-Complianceregeln	ChangeQueueState(kmdf), DriverCreate(kmdf), DrvAckIoStop(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)