WdfIoQueueAssignForwardProgressPolicy-Funktion (wdfio.h)

Artikel
03/22/2025

[Gilt nur für KMDF]

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

Syntax

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

Die Parameter

[in] Queue

Ein Handle zu einem 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-Wertezurückgeben. Wenn der EvtIoAllocateResourcesForReservedRequest Rückruffunktion einen Fehlerstatuswert zurückgibt, gibt WdfIoQueueAssignForwardProgressPolicy diesen Wert zurück.

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

Bemerkungen

DieWdfIoQueueAssignForwardProgressPolicy Methode erstellt Anforderungsobjekte, die vom Framework für Situationen mit geringem Arbeitsspeicher reserviert werden, 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 parameter Queue darstellt, die Standard-E/A-Warteschlange eines Geräts oder eine Warteschlange sein, für die Ihr Treiber WdfDeviceConfigureRequestDispatchingaufgerufen hat. Der Treiber kann WdfIoQueueAssignForwardProgressPolicy jederzeit aufrufen, nachdem er WdfDeviceConfigureRequestDispatchingaufgerufen hat.

In KMDF-Versionen 1.11 und höher kann die E/A-Warteschlange, die der parameter Queue darstellt, eine beliebige Warteschlange sein, die eine Anforderung direkt aus dem Framework empfängt. Beispielsweise kann der Treiber eine Warteschlange angeben, an die irps dynamisch weitergeleitet .

Bevor WdfIoQueueAssignForwardProgressPolicy zurückgegeben wird, führt das Framework folgendes aus:

Erstellt und speichert die Anzahl der Anforderungsobjekte, die der Treiber für die TotalForwardProgressRequests Member der WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY-Struktur angegeben hat.
Wenn der zuvor WdfDeviceInitSetRequestAttributesaufgerufene Treiber enthält jede Zuordnung kontextbereich, der WdfDeviceInitSetRequestAttributes angegeben.
Ruft die EvtIoAllocateResourcesForReservedRequest Rückruffunktion für jedes Anforderungsobjekt auf, das vom Framework erstellt wird.

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 geringem Arbeitsspeicher verursacht.)

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

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

Beispiele

In diesem Codebeispiel wird eine zuvor erstellte E/A-Warteschlange so konfiguriert, dass Schreibanforderungen empfangen werden, und anschließend wird der garantierte 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
Minimale KMDF-Version	1.9
Kopfzeile	wdfio.h (einschließen Wdf.h)
Bibliothek	Wdf01000.sys (siehe Framework-Bibliotheksversionsverwaltung.)
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf)

Siehe auch

EvtIoAllocateResourcesForReservedRequest

WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY

WdfDeviceConfigureRequestDispatching

Freigeben über