WdfIoQueueAssignForwardProgressPolicy-Funktion (wdfio.h)

  • Artikel

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

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 WdfDeviceInitSetRequestAttributesaufruft 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