WdfIoQueueReadyNotify-Funktion (wdfio.h)

[Gilt für KMDF und UMDF]

Die WdfIoQueueReadyNotify Methode registriert (oder deregistert) eine Ereignisrückruffunktion, 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
);

Die Parameter

[in] Queue

Ein Handle zu einem Framework-Warteschlangenobjekt.

[in, optional] QueueReady

Ein Zeiger auf einen vom Treiber bereitgestellten EvtIoQueueState Rückruffunktion, wenn sich der Treiber für die bereite Benachrichtigung registriert, oder NULL-, wenn der Treiber die Registrierung deaktiviert.

[in, optional] Context

Ein nicht typisiertes Zeiger auf vom Treiber bereitgestellte Kontextinformationen, die das Framework an die EvtIoQueueState Rückruffunktion übergibt, wenn der Treiber für die Benachrichtigung bereit registriert wird, oder NULL-, wenn der Treiber die Registrierung deaktiviert.

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 einen ungültigen Handle bereitgestellt.
STATUS_INVALID_DEVICE_REQUEST	Dieser Wert wird zurückgegeben, wenn einer der folgenden Aktionen auftritt: Das DispatchType Mitglied 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 der Benachrichtigungsrückruffunktion aufzurufen, aber eine Rückruffunktion ist nicht registriert, oder der Treiber hat nicht WdfIoQueueStop oder WdfIoQueueStopSynchronouslyaufgerufen.

 

Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.

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

Bemerkungen

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 keine zuvor übermittelten Anforderungen aus der Warteschlange besitzt, die er noch nicht abgeschlossen hat. Sie können die IRQL ändern, bei 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 Verteilermethode 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 parameter QueueReady auf NULL-festgelegt ist. Der Treiber muss jedoch zuerst WdfIoQueueStop oder WdfIoQueueStopSynchronously 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, ist es möglich, dass das Framework die Rückruffunktion aufruft, bevor WdfIoQueueReadyNotify zurückgegeben wird.

Weitere Informationen zur WdfIoQueueReadyNotify-Methode finden Sie unter Dispatching Methods for I/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
Minimale KMDF-Version	1.0
Mindest-UMDF-Version	2.0
Kopfzeile	wdfio.h (einschließen Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Siehe auch

EvtIoQueueState

WDF_IO_QUEUE_CONFIG

WdfIoQueueRetrieveNextRequest

WdfIoQueueRetrieveRequestByFileObject