WdfIoQueueAssignForwardProgressPolicy-Funktion (wdfio.h)

Artikel
02/29/2024

[Gilt nur für KMDF]

Die WdfIoQueueAssignForwardProgressPolicy-Methode ermöglicht es dem Framework, den Vorwärtsfortschritt für eine angegebene E/A-Warteschlange zu garantieren.

Syntax

NTSTATUS WdfIoQueueAssignForwardProgressPolicy(
  [in] WDFQUEUE                              Queue,
  [in] PWDF_IO_QUEUE_FORWARD_PROGRESS_POLICY ForwardProgressPolicy
);

Parameter

[in] Queue

Ein Handle für ein Framework-Warteschlangenobjekt.

[in] ForwardProgressPolicy

Ein Zeiger auf eine vom Treiber zugewiesene WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY-Struktur .

Rückgabewert

WdfIoQueueAssignForwardProgressPolicy 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_FORWARD_PROGRESS_POLICY-Struktur ist falsch.
STATUS_INSUFFICIENT_RESOURCES	Der verfügbare Arbeitsspeicher ist zu niedrig.

Diese Methode kann auch andere NTSTATUS-Werte zurückgeben. Wenn die Rückruffunktion EvtIoAllocateResourcesForReservedRequest des Treibers einen Fehler status Wert zurückgibt, gibt WdfIoQueueAssignForwardProgressPolicy diesen Wert zurück.

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

Hinweise

DieWdfIoQueueAssignForwardProgressPolicy-Methode erstellt Anforderungsobjekte, die das Framework für Situationen mit geringem Arbeitsspeicher reserviert, und registriert Rückruffunktionen, die das Framework aufruft, um Situationen mit geringem Arbeitsspeicher zu verarbeiten.

In KMDF Version 1.9 muss die E/A-Warteschlange, die der Queue-Parameter darstellt, die Standard-E/A-Warteschlange eines Geräts oder eine Warteschlange sein, für die Ihr Treiber WdfDeviceConfigureRequestDispatching aufgerufen hat. Der Treiber kann WdfIoQueueAssignForwardProgressPolicy jederzeit aufrufen, nachdem er WdfDeviceConfigureRequestDispatching aufgerufen hat.

In KMDF-Versionen 1.11 und höher kann die E/A-Warteschlange, die der Queue-Parameter darstellt, eine beliebige Warteschlange sein, die eine Anforderung direkt vom Framework empfängt. Der Treiber kann beispielsweise eine Warteschlange angeben, an die IRPs dynamisch weitergeleitet werden.

Bevor WdfIoQueueAssignForwardProgressPolicy zurückgibt, führt das Framework Folgendes aus:

Erstellt und speichert die Anzahl von Anforderungsobjekten, die der Treiber für den TotalForwardProgressRequests-Member der WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY-Struktur angegeben hat.
Wenn der Treiber zuvor WdfDeviceInitSetRequestAttributes aufgerufen hat, enthält jede Zuordnung Kontextraum, den WdfDeviceInitSetRequestAttributes angegeben hat.
Ruft die EvtIoAllocateResourcesForReservedRequest-Rückruffunktion des Treibers für jedes Anforderungsobjekt auf, das das Framework erstellt.

Nachdem der Treiber WdfIoQueueAssignForwardProgressPolicy aufgerufen hat, um reservierte Anforderungsobjekte zu erstellen, verwendet das Framework diese reservierten Objekte, wenn der Versuch, ein neues Anforderungsobjekt zu erstellen, fehlschlägt. (In der Regel werden solche Fehler durch Situationen mit wenig Arbeitsspeicher verursacht.)

Das Framework löscht seine reservierten Anforderungsobjekte nur, wenn es das Frameworkwarteschlangenobjekt löscht, zu dem sie gehören. Wenn Ihr Treiber WdfDeviceInitSetRequestAttributes aufruft und eine EvtCleanupCallback - oder EvtDestroyCallback-Rückruffunktion für seine Anforderungsobjekte angibt, ruft das Framework diese Rückruffunktionen für seine reservierten Anforderungsobjekte auf, wenn es die Objekte löscht.

Weitere Informationen zur WdfIoQueueAssignForwardProgressPolicy-Methode und zur Verwendung der garantierten Vorwärtsfortschrittsfunktion des Frameworks finden Sie unter Garantieren des Vorwärtsfortschritts von E/A-Vorgängen.

Beispiele

In diesem Codebeispiel wird eine zuvor erstellte E/A-Warteschlange für den Empfang von Schreibanforderungen konfiguriert, und anschließend wird ein garantierter Vorwärtsfortschritt für die Warteschlange aktiviert.

#define MAX_RESERVED_REQUESTS 10

WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY queueForwardProgressPolicy;
WDFQUEUE writeQueue;
NTSTATUS status = STATUS_SUCCESS;
...
status = WdfDeviceConfigureRequestDispatching(
             device,
             writeQueue,
             WdfRequestTypeWrite
             );
if(!NT_SUCCESS(status)) {
    return status;
}
WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY_DEFAULT_INIT(
    &queueForwardProgressPolicy,
    MAX_RESERVED_REQUESTS
    );
status = WdfIoQueueAssignForwardProgressPolicy(
             writeQueue,
             &queueForwardProgressPolicy
             );
if(!NT_SUCCESS(status)) {
    return status;
}

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.9
Kopfzeile	wdfio.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (siehe Versionsverwaltung der Frameworkbibliothek).)
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf)

Weitere Informationen

EvtIoAllocateResourcesForReservedRequest

WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY

WdfDeviceConfigureRequestDispatching

Freigeben über