WdfUsbTargetDeviceFormatRequestForCyclePort-Funktion (wdfusb.h)

Artikel
02/29/2024

[Gilt nur für KMDF]

Die WdfUsbTargetDeviceFormatRequestForCyclePort-Methode erstellt eine Power-Cycle-Anforderung für den Port, an den ein angegebenes Gerät angefügt ist. Die Anforderung wird jedoch nicht gesendet.

Syntax

NTSTATUS WdfUsbTargetDeviceFormatRequestForCyclePort(
  [in] WDFUSBDEVICE UsbDevice,
  [in] WDFREQUEST   Request
);

Parameter

[in] UsbDevice

Ein Handle für ein USB-Geräteobjekt, das von einem vorherigen Aufruf von WdfUsbTargetDeviceCreateWithParameters abgerufen wurde.

[in] Request

Ein Handle für ein Frameworkanforderungsobjekt. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

Rückgabewert

WdfUsbTargetDeviceFormatRequestForCyclePort gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls kann diese Methode einen der folgenden Werte zurückgeben:

Rückgabecode	Beschreibung
STATUS_INVALID_DEVICE_STATE	Das USB-Gerät des Geräts war nicht verfügbar.
STATUS_INSUFFICIENT_RESOURCES	Nicht genügend Arbeitsspeicher war verfügbar.

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

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

Hinweise

Verwenden Sie WdfUsbTargetDeviceFormatRequestForCyclePort gefolgt von WdfRequestSend, um eine Energiezyklusanforderung synchron oder asynchron zu senden. Alternativ können Sie die WdfUsbTargetDeviceCyclePortSynchronously-Methode verwenden, um eine Anforderung synchron zu senden.

Bevor der Treiber WdfRequestSend aufruft, muss er WdfIoTargetStop aufrufen und alle E/A-Anforderungen abschließen oder abbrechen , die er an das E/A-Ziel gesendet hat. Der Treiber darf keine zusätzlichen E/A-Anforderungen an das E/A-Ziel senden, bis die Zyklusanforderung abgeschlossen ist.

Sie können eine E/A-Anforderung weiterleiten, die Ihr Treiber in einer E/A-Warteschlange erhalten hat, oder Sie können eine neue Anforderung erstellen und senden.

Um eine E/A-Anforderung weiterzuleiten, die Ihr Treiber in einer E/A-Warteschlange empfangen hat, geben Sie das Handle der empfangenen Anforderung für den Request-Parameter der WdfUsbTargetDeviceFormatRequestForCyclePort-Methode an.

Um eine neue E/A-Anforderung zu erstellen, rufen Sie WdfRequestCreate auf , um ein Anforderungsobjekt vorab zu allocatieren. Geben Sie das Anforderungshandle für den Request-Parameter der WdfUsbTargetDeviceFormatRequestForCyclePort-Methode an. Sie können das Anforderungsobjekt wiederverwenden, indem Sie WdfRequestReuse aufrufen. Die Rückruffunktion EvtDriverDeviceAdd ihres Treibers kann Anforderungsobjekte für ein Gerät vorab zuweisungen.

Nach dem Aufrufen von WdfUsbTargetDeviceFormatRequestForCyclePort zum Formatieren einer E/A-Anforderung muss der Treiber WdfRequestSend aufrufen, um die Anforderung (synchron oder asynchron) an ein E/A-Ziel zu senden. Dieser Aufruf von WdfRequestSend muss unter IRQL = PASSIVE_LEVEL erfolgen.

Mehrere Aufrufe von WdfUsbTargetDeviceFormatRequestForCyclePort , die dieselbe Anforderung verwenden, verursachen keine zusätzlichen Ressourcenzuordnungen. Daher kann die EvtDriverDeviceAdd-Rückruffunktion Ihres Treibers WdfRequestCreate aufrufen, um die Möglichkeit zu verringern, dass WdfRequestCreate zurückgegeben STATUS_INSUFFICIENT_RESOURCES wird, um ein oder mehrere Anforderungsobjekte für ein Gerät vorab zuordnen. Der Treiber kann jedes Anforderungsobjekt anschließend wiederverwenden ( Aufrufen von WdfRequestReuse), reformatieren (aufrufen von WdfUsbTargetDeviceFormatRequestForCyclePort) und erneut senden (Aufrufen von WdfRequestSend), ohne einen STATUS_INSUFFICIENT_RESOURCES Rückgabewert aus einem späteren Aufruf von WdfRequestCreate zu riskieren. Alle nachfolgenden Aufrufe von WdfUsbTargetDeviceFormatRequestForCyclePort für das wiederverwendete Anforderungsobjekt geben STATUS_SUCCESS zurück, wenn sich die Parameterwerte nicht ändern. (Wenn der Treiber nicht jedes Mal dieselbe Methode zur Anforderungsformatierung aufruft, werden möglicherweise zusätzliche Ressourcen zugewiesen.)

Weitere Informationen zur WdfUsbTargetDeviceFormatRequestForCyclePort-Methode und USB-E/A-Zielen finden Sie unter USB-E/A-Ziele.

Beispiele

Im folgenden Codebeispiel wird eine Energiezyklusanforderung formatiert, eine CompletionRoutine-Rückruffunktion registriert und die Anforderung an ein E/A-Ziel gesendet.

status = WdfUsbTargetDeviceFormatRequestForCyclePort(
                                            UsbDevice,
                                            request
                                            );
if (!NT_SUCCESS(status)){
    return status;
}
WdfRequestSetCompletionRoutine(
                               request,
                               MyCompletionRoutine,
                               NULL
                               );

if (WdfRequestSend(
                   request,
                   WdfUsbTargetDeviceGetIoTarget(UsbDevice),
                   NULL
                   ) == FALSE) {
    status = WdfRequestGetStatus(request);
}

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
Kopfzeile	wdfusb.h (einschließlich Wdfusb.h)
Bibliothek	Wdf01000.sys (siehe Versionierung der Frameworkbibliothek.)
IRQL	<=DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)