WdfIoTargetPurge-Funktion (wdfiotarget.h)

Artikel
08/08/2023

[Gilt für KMDF und UMDF]

Die WdfIoTargetPurge-Methode bricht alle E/A-Anforderungen ab, die an ein lokales, remote oder spezialisiertes E/A-Ziel in die Warteschlange gestellt werden, und verhindert, dass neue E/A-Anforderungen in die Warteschlange gestellt werden. Die Methode versucht auch, E/A-Anforderungen abzubrechen, die die Warteschlange des E/A-Ziels verlassen und niedrigere Treiber eingegeben haben.

Syntax

void WdfIoTargetPurge(
  [in] WDFIOTARGET                   IoTarget,
  [in] WDF_IO_TARGET_PURGE_IO_ACTION Action
);

Parameter

[in] IoTarget

Ein Handle für ein lokales oder Remote-E/A-Zielobjekt, das von einem vorherigen Aufruf von WdfDeviceGetIoTarget oder WdfIoTargetCreate oder von einer Methode abgerufen wurde, die von einem spezialisierten E/A-Ziel bereitgestellt wird, z. B. WdfUsbTargetPipeGetIoTarget.

[in] Action

Ein WDF_IO_TARGET_PURGE_IO_ACTION typisierter Wert, der angibt, ob das Framework auf die Rückgabe von WdfIoTargetPurge warten soll, bis alle übermittelten Anforderungen abgeschlossen oder abgebrochen wurden.

Rückgabewert

Keine

Bemerkungen

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

Wenn der Treiber zuvor WdfUsbTargetPipeConfigContinuousReader aufgerufen hat, muss WdfIoTargetPurge unter IRQL = PASSIVE_LEVEL aufgerufen werden. Wenn der Treiber WdfUsbTargetPipeConfigContinuousReader nicht aufgerufen hat und der Action-Parameter von WdfIoTargetPurgeWdfIoTargetPurge ist, kann WdfIoTargetPurge unter IRQL <= DISPATCH_LEVEL aufgerufen werden. Andernfalls muss WdfIoTargetPurge unter IRQL = PASSIVE_LEVEL aufgerufen werden.

Um WdfIoTargetPurge zu einem synchronen Aufruf zu machen, kann der Treiber den WdfIoTargetPurgeIoAndWait-Wert des Action-Parameters festlegen. In diesem Fall wartet WdfIoTargetPurge auf die Rückgabe, bis alle übermittelten Anforderungen abgeschlossen oder abgebrochen wurden.

Nachdem ein Treiber WdfIoTargetPurge aufgerufen hat, kann er trotzdem eine Anforderung an das Ziel senden, indem er das WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE-Flag in der WDF_REQUEST_SEND_OPTIONS Struktur der Anforderung festlegt. Beispielsweise kann ein Treiber eine Anforderung, z. B. eine Anforderung zum Zurücksetzen einer USB-Pipe (siehe WdfUsbTargetPipeResetSynchronously), an ein Gerät senden, nachdem der Treiber WdfIoTargetPurge aufgerufen hat.

Wenn ein Treiber WdfIoTargetPurge aufruft, versucht das Framework nicht, E/A-Anforderungen abzubrechen oder auf E/A-Anforderungen zu warten, die zuvor mit dem WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE-Flag oder dem WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET-Flag in der WDF_REQUEST_SEND_OPTIONS Struktur der Anforderung an das Ziel gesendet wurden.

Nachdem ein Treiber eine E/A-Warteschlange gelöscht hat, kann er die Warteschlange neu starten, indem er WdfIoTargetStart aufruft.

Ihr Treiber muss WdfIoTargetStart, WdfIoTargetStop und WdfIoTargetPurge synchron aufrufen. Nachdem der Treiber eine dieser Funktionen aufgerufen hat, darf er keine der anderen Funktionen aufrufen, bis der vorherige Aufruf zurückgegeben wird.

Ihr Treiber kann WdfIoTargetPurge mehrmals aufrufen, ohne WdfIoTargetStart aufzurufen. Ihr Treiber kann z. B. die folgenden Aktionen ausführen:

Rufen Sie WdfIoTargetPurge auf, und geben Sie den AktionswertWdfIoTargetPurgeIo an.
Bestimmen Sie, ob das Ziel die Verarbeitung von E/A-Anforderungen fortsetzen soll.
Wenn das Ziel fortgesetzt werden soll, rufen Sie WdfIoTargetStart auf. Rufen Sie andernfalls WdfIoTargetPurge mit dem AktionswertWdfIoTargetPurgeIoAndWait erneut auf.

Weitere Informationen zu E/A-Zielzuständen finden Sie unter Steuern des Status eines allgemeinen E/A-Ziels.

Weitere Informationen zu E/A-Zielen finden Sie unter Verwenden von E/A-Zielen.

Beispiele

Das folgende Codebeispiel zeigt, wie eine EvtDeviceD0Exit-RückruffunktionWdfIoTargetPurge aufrufen kann, wenn der Treiber einen kontinuierlichen Reader für eine USB-Pipe verwendet.

NTSTATUS
MyEvtDeviceD0Exit(
    IN  WDFDEVICE Device,
    IN  WDF_POWER_DEVICE_STATE TargetState
)
{
    PDEVICE_CONTEXT  pDeviceContext;
    pDeviceContext = GetMyDeviceContext(Device);

    WdfIoTargetPurge(
                    WdfUsbTargetPipeGetIoTarget(pDeviceContext->InterruptPipe),
                    WdfIoTargetPurgeIoAndWait
                    );

    return STATUS_SUCCESS;
}

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.11
UMDF-Mindestversion	2.0
Kopfzeile	wdfiotarget.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	Weitere Informationen finden Sie im Abschnitt mit den Hinweisen.
DDI-Complianceregeln	DriverCreate(kmdf)