WdfIoTargetPurge-Funktion (wdfiotarget.h)

[Gilt für KMDF und UMDF]

Die WdfIoTargetPurge Methode bricht alle E/A-Anforderungen in die Warteschlange eines lokalen, Remote- oder spezialisierten E/A-Ziels ab und verhindert, dass neue E/A-Anforderungen in die Warteschlange gestellt werden. Die Methode versucht auch, E/A-Anforderungen abzubrechen, die die E/A-Zielwarteschlange verlassen und niedrigere Treiber eingegeben haben.

Syntax

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

Die Parameter

[in] IoTarget

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

[in] Action

Ein WDF_IO_TARGET_PURGE_IO_ACTION-typed-Wert, der angibt, ob das Framework warten soll, um von WdfIoTargetPurge zurückzugeben, bis alle übermittelten Anforderungen abgeschlossen oder abgebrochen werden.

Rückgabewert

Nichts

Bemerkungen

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

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

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

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

Wenn ein Treiber WdfIoTargetPurge-aufruft, versucht das Framework nicht, E/A-Anforderungen abzubrechen oder zu warten, die zuvor mithilfe des WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE Flags oder des WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET Flags 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 WdfIoTargetStartaufgerufen wird.

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

Ihr Treiber kann WdfIoTargetPurge- mehrmals aufrufen, ohne WdfIoTargetStartaufzurufen. Ihr Treiber kann z. B. folgende Aktionen ausführen:

1. Rufen Sie WdfIoTargetPurge auf, und geben Sie einen Action Wert von WdfIoTargetPurgeIoan.
2. Bestimmen Sie, ob das Ziel die Verarbeitung von E/A-Anforderungen fortsetzen soll.
3. Wenn das Ziel fortgesetzt werden soll, rufen Sie WdfIoTargetStartauf. Rufen Sie andernfalls WdfIoTargetPurge erneut mit einem Action- Wert von WdfIoTargetPurgeIoAndWaitauf.

Weitere Informationen zu E/A-Zielzuständen finden Sie unter Controlling a General I/O Target's State.

Weitere Informationen zu E/A-Zielen finden Sie unter Using I/O Targets.

Beispiele

Das folgende Codebeispiel zeigt, wie eine EvtDeviceD0Exit- Rückruffunktion WdfIoTargetPurgeaufrufen kann, wenn der Treiber einen fortlaufenden 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
Minimale KMDF-Version	1.11
Mindest-UMDF-Version	2.0
Kopfzeile	wdfiotarget.h (include Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	Siehe Abschnitt "Hinweise".
DDI-Complianceregeln	DriverCreate(kmdf)

Siehe auch

WDF_IO_TARGET_PURGE_IO_ACTION

WdfIoTargetCreate

WdfIoTargetGetState

WdfIoTargetStart-

WdfIoTargetStop-