WdfUsbTargetDeviceFormatRequestForCyclePort-Funktion (wdfusb.h)
[Gilt nur für KMDF]
Die WdfUsbTargetDeviceFormatRequestForCyclePort- Methode erstellt eine Stromzyklusanforderung für den Port, an den ein angegebenes Gerät angefügt ist, aber die Anforderung wird nicht gesendet.
Syntax
NTSTATUS WdfUsbTargetDeviceFormatRequestForCyclePort(
[in] WDFUSBDEVICE UsbDevice,
[in] WDFREQUEST Request
);
Parameter
[in] UsbDevice
Ein Handle für ein USB-Geräteobjekt, das aus einem vorherigen Aufruf von WdfUsbTargetDeviceCreateWithParametersabgerufen wurde.
[in] Request
Ein Handle zu einem Framework-Anforderungsobjekt. 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 |
|---|---|
|
Das USB-Gerät des Geräts war nicht verfügbar. |
|
Nicht genügend Arbeitsspeicher verfügbar. |
Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.
Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.
Bemerkungen
Verwenden Sie WdfUsbTargetDeviceFormatRequestForCyclePort, gefolgt von WdfRequestSend-, um eine Power-Cycle-Anforderung entweder 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 oder alle E/A-Anforderungen abbrechen, die er an das E/A-Ziel gesendet hat. Der Treiber darf erst dann zusätzliche E/A-Anforderungen an das E/A-Ziel senden, wenn 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 WdfUsbTargetDeviceFormatRequestForCyclePort Methode Request Parameter an.
Rufen Sie WdfRequestCreate auf, um eine neue E/A-Anforderung zu erstellen. Geben Sie den Anforderungshandle für den WdfUsbTargetDeviceFormatRequestForCyclePort Parameter der Request Methode an. Sie können das Anforderungsobjekt wiederverwenden, indem Sie WdfRequestReuseaufrufen. Die EvtDriverDeviceAdd Rückruffunktion Ihres Treibers kann Anforderungsobjekte für ein Gerät vorab allocatieren.
Nach dem Aufrufen 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 bei IRQL = PASSIVE_LEVEL erfolgen.
Mehrere Aufrufe an WdfUsbTargetDeviceFormatRequestForCyclePort, die dieselbe Anforderung verwenden, verursachen keine zusätzlichen Ressourcenzuordnungen. Um die Chance zu verringern, dass WdfRequestCreate- STATUS_INSUFFICIENT_RESOURCES zurückgibt, kann die EvtDriverDeviceAdd- Rückruffunktion WdfRequestCreate aufrufen, um mindestens ein Anforderungsobjekt für ein Gerät vorab bereitzustellen. Der Treiber kann anschließend wiederverwendet werden (aufruf WdfRequestReuse), neu formatieren (Aufruf WdfUsbTargetDeviceFormatRequestForCyclePort) und erneut senden (WdfRequestSend) jedes Anforderungsobjekt ohne Risiko eines STATUS_INSUFFICIENT_RESOURCES Rückgabewerts von einem späteren Aufruf an WdfRequestCreate. Alle nachfolgenden Aufrufe von WdfUsbTargetDeviceFormatRequestForCyclePort- für das wiederverwendete Anforderungsobjekt geben STATUS_SUCCESS zurück, wenn parameterwerte nicht geändert werden. (Wenn der Treiber nicht jedes Mal dieselbe Anforderungsformatierungsmethode aufruft, werden möglicherweise zusätzliche Ressourcen zugeordnet.)
Weitere Informationen zu den WdfUsbTargetDeviceFormatRequestForCyclePort Methode und USB-E/A-Zielen finden Sie unter USB-E/A-Ziele.
Beispiele
Im folgenden Codebeispiel wird eine Power-Cycle-Anforderung 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- | Universal |
| Minimale KMDF-Version | 1.0 |
| Header- | wdfusb.h (include Wdfusb.h) |
| Library | Wdf01000.sys (siehe Framework-Bibliotheksversionsverwaltung.) |
| IRQL- | <=DISPATCH_LEVEL |
| DDI-Complianceregeln | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf) |