WdfIoQueueReadyNotify-Funktion (wdfio.h)

Artikel
02/27/2024

[Gilt für KMDF und UMDF]

Die WdfIoQueueReadyNotify-Methode registriert (oder hebt die Registrierung) einer Ereignisrückruffunktion auf, die das Framework jedes Mal aufruft, wenn eine angegebene E/A-Warteschlange, die zuvor leer war, eine oder mehrere E/A-Anforderungen empfängt.

Syntax

NTSTATUS WdfIoQueueReadyNotify(
  [in]           WDFQUEUE               Queue,
  [in, optional] PFN_WDF_IO_QUEUE_STATE QueueReady,
  [in, optional] WDFCONTEXT             Context
);

Parameter

[in] Queue

Ein Handle für ein Framework-Warteschlangenobjekt.

[in, optional] QueueReady

Ein Zeiger auf eine vom Treiber bereitgestellte EvtIoQueueState-Rückruffunktion , wenn der Treiber für die bereite Benachrichtigung registriert wird, oder NULL , wenn der Treiber die Registrierung abnimmt.

[in, optional] Context

Ein nicht typisierter Zeiger auf vom Treiber bereitgestellte Kontextinformationen, die das Framework an die EvtIoQueueState-Rückruffunktion übergibt, wenn sich der Treiber für die bereite Benachrichtigung registriert, oder NULL , wenn der Treiber die Registrierung abhebt.

Rückgabewert

WdfIoQueueReadyNotify 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	Der Treiber hat ein ungültiges Handle bereitgestellt.
STATUS_INVALID_DEVICE_REQUEST	Dieser Wert wird zurückgegeben, wenn einer der folgenden Fehler auftritt: Das DispatchType-Element der WDF_IO_QUEUE_CONFIG-Struktur der angegebenen E/ A-Warteschlange ist nicht WdfIoQueueDispatchManual. Der Treiber hatte zuvor WdfIoQueueReadyNotify aufgerufen und eine EvtIoQueueState-Rückruffunktion registriert. Der Treiber versucht, die Registrierung seiner Benachrichtigungsrückruffunktion aufzuheben, aber eine Rückruffunktion ist nicht registriert, oder der Treiber hat WdfIoQueueStop oder WdfIoQueueStopSynchronously nicht aufgerufen.

Rückgabecode

Beschreibung

STATUS_INVALID_PARAMETER

Der Treiber hat ein ungültiges Handle bereitgestellt.

STATUS_INVALID_DEVICE_REQUEST

Dieser Wert wird zurückgegeben, wenn einer der folgenden Fehler auftritt:

Das DispatchType-Element der WDF_IO_QUEUE_CONFIG-Struktur der angegebenen E/ A-Warteschlange ist nicht WdfIoQueueDispatchManual.
Der Treiber hatte zuvor WdfIoQueueReadyNotify aufgerufen und eine EvtIoQueueState-Rückruffunktion registriert.
Der Treiber versucht, die Registrierung seiner Benachrichtigungsrückruffunktion aufzuheben, aber eine Rückruffunktion ist nicht registriert, oder der Treiber hat WdfIoQueueStop oder WdfIoQueueStopSynchronously nicht aufgerufen.

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

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

Hinweise

Nachdem ein Treiber WdfIoQueueReadyNotify aufgerufen hat, um eine EvtIoQueueState-Rückruffunktion zu registrieren, ruft das Framework die Rückruffunktion jedes Mal auf, wenn sich der Status der angegebenen Warteschlange von leer in nicht leer ändert. Insbesondere ruft das Framework EvtIoQueueState auf, wenn eine Anforderung in einer leeren Warteschlange eingeht, auch wenn der Treiber noch über zuvor übermittelte Anforderungen aus der Warteschlange verfügt, die er noch nicht abgeschlossen hat. Sie können die IRQL ändern, an der der Rückruf ausgeführt wird, indem Sie executionLevel in WDF_OBJECT_ATTRIBUTES zum Zeitpunkt der Warteschlangenerstellung angeben. Weitere Informationen finden Sie im Abschnitt Hinweise vonEVT_WDF_IO_QUEUE_STATE.

Das Framework ruft EvtIoQueueState nicht auf, während die angegebene Warteschlange beendet wird. Wenn die Warteschlange gestartet wird, ruft das Framework EvtIoQueueState auf, wenn die Warteschlange nicht leer ist.

Ihr Treiber kann WdfIoQueueReadyNotify nur für E/A-Warteschlangen aufrufen, die die manuelle Verteilmethode verwenden.

Die EvtIoQueueState-Rückruffunktion ruft in der Regel WdfIoQueueRetrieveNextRequest oder WdfIoQueueRetrieveRequestByFileObject in einer Schleife auf, um alle Anforderungen abzurufen, die seit der letzten Ausführung der Rückruffunktion eingegangen sind.

Um zu verhindern, dass das Framework die EvtIoQueueState-Rückruffunktion aufruft , muss der Treiber WdfIoQueueReadyNotify erneut aufrufen, wobei der QueueReady-Parameter auf NULL festgelegt ist. Der Treiber muss jedoch zuerst WdfIoQueueStop oder WdfIoQueueStopSynchronly aufrufen, um die E/A-Warteschlange zu beenden. Der Treiber kann anschließend WdfIoQueueStart aufrufen, um die Warteschlange neu zu starten.

Wenn ein Treiber WdfIoQueueReadyNotify aufruft, um eine EvtIoQueueState-Rückruffunktion zu registrieren, kann das Framework die Rückruffunktion aufrufen, bevor WdfIoQueueReadyNotify zurückgegeben wird.

Weitere Informationen zur WdfIoQueueReadyNotify-Methode finden Sie unter Dispatching Methods for E/O Requests.

Beispiele

Im folgenden Codebeispiel wird die EvtIoQueueReady-Funktion eines Treibers registriert, sodass diese Funktion aufgerufen wird, wenn die angegebene E/A-Warteschlange eine E/A-Anforderung empfängt.

Status = WdfIoQueueReadyNotify(
                               ReadQueue,
                               EvtIoQueueReady,
                               myQueueContext
                               );

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	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Weitere Informationen

EvtIoQueueState

WDF_IO_QUEUE_CONFIG

WdfIoQueueRetrieveNextRequest

WdfIoQueueRetrieveRequestByFileObject

Freigeben über