WdfIoTargetStop-Funktion (wdfiotarget.h)

Artikel
02/27/2024

[Gilt für KMDF und UMDF]

Die WdfIoTargetStop-Methode beendet das Senden von Anforderungen in die Warteschlange an ein lokales oder Remote-E/A-Ziel.

Syntax

void WdfIoTargetStop(
  [in] WDFIOTARGET                  IoTarget,
  [in] WDF_IO_TARGET_SENT_IO_ACTION Action
);

Parameter

[in] IoTarget

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

[in] Action

Ein WDF_IO_TARGET_SENT_IO_ACTION typisierter Wert, der angibt, wie das Framework E/A-Anforderungen behandeln soll, die der Treiber an das E/A-Ziel gesendet hat, wenn das Ziel die Anforderungen nicht abgeschlossen hat.

Rückgabewert

Keine

Bemerkungen

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

Wenn Ihr Treiber wiederherstellbare Gerätefehler erkennen kann, möchten Sie möglicherweise, dass Ihr Treiber WdfIoTargetStop aufruft , um das Senden von Anforderungen vorübergehend einzustellen. Rufen Sie später WdfIoTargetStart auf, um das Senden von Anforderungen fortzusetzen.

Während der Beendigung akzeptiert ein E/A-Ziel weiterhin neue Anforderungen, übermittelt die Anforderungen in der Warteschlange jedoch nicht an den entsprechenden Treiber.

Weitere Informationen zu möglichen Zuständen für E/A-Ziele finden Sie unter Steuern des Status eines allgemeinen E/A-Ziels.

Wenn ein Treiber WdfUsbTargetPipeConfigContinuousReader aufruft, um einen kontinuierlichen Reader für eine USB-Pipe zu konfigurieren, muss die EvtDeviceD0Exit-Rückruffunktion des Treibers WdfIoTargetStop aufrufen, um den Reader anzuhalten.

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

Wenn ein Treiber WdfIoTargetStop 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.

Ihr Treiber muss WdfIoTargetStart und WdfIoTargetStop synchron aufrufen. Nachdem der Treiber eine dieser Funktionen aufgerufen hat, darf er keine der beiden Funktionen aufrufen, bevor der erste Aufruf zurückgibt.

Ihr Treiber kann WdfIoTargetStop mehrmals aus einem einzelnen Thread aufrufen, ohne WdfIoTargetStart aufzurufen. Ihr Treiber kann z. B. die folgenden Aktionen ausführen:

Rufen Sie WdfIoTargetStop auf, und geben Sie den AktionswertWdfIoTargetLeaveSentIoPending 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 WdfIoTargetStop mit dem AktionswertWdfIoTargetCancelSentIo erneut auf.

HinweisWdfIoTargetStop ist nicht threadsicher. Es ist nicht sicher, WdfIoTargetStop gleichzeitig aus verschiedenen Threads aufzurufen.

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

Wenn der Treiber WdfUsbTargetPipeConfigContinuousReader für die Pipe aufgerufen hat, muss WdfIoTargetStop unter IRQL = PASSIVE_LEVEL aufgerufen werden.

Wenn der Treiber nicht WdfUsbTargetPipeConfigContinuousReader aufgerufen hat und der Action-Parameter von WdfIoTargetStopWdfIoTargetLeaveSentIoPending ist, kann WdfIoTargetStop unter IRQL <= DISPATCH_LEVEL aufgerufen werden. Andernfalls wird WdfIoTargetStop unter IRQL = PASSIVE_LEVEL aufgerufen.

Beispiele

Das folgende Codebeispiel zeigt, wie eine EvtDeviceD0Exit-RückruffunktionWdfIoTargetStop aufrufen 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);

    WdfIoTargetStop(
                    WdfUsbTargetPipeGetIoTarget(pDeviceContext->InterruptPipe),
                    WdfIoTargetCancelSentIo
                    );

    return STATUS_SUCCESS;
}

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
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), FailD0EntryIoTargetState(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)