WdfUsbTargetPipeFormatRequestForReset-Funktion (wdfusb.h)
[Gilt für KMDF und UMDF]
Die WdfUsbTargetPipeFormatRequestForResetForReset-Methode erstellt eine Zurücksetzungsanforderung für ein angegebenes USB-Pipe, sendet jedoch nicht die Anforderung.
Syntax
NTSTATUS WdfUsbTargetPipeFormatRequestForReset(
[in] WDFUSBPIPE Pipe,
[in] WDFREQUEST Request
);
Parameter
[in] Pipe
Ein Handle zu einem Framework-Pipeobjekt, das durch Aufrufen WdfUsbInterfaceGetConfiguredPipeabgerufen wurde.
[in] Request
Ein Handle zu einem Framework-Anforderungsobjekt. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
Rückgabewert
WdfUsbTargetPipeFormatRequestForReset gibt den Fertigstellungsstatuswert des USB-E/A-Ziels zurück, wenn der Vorgang erfolgreich ist. Andernfalls kann diese Methode einen der folgenden Werte zurückgeben:
| Rückgabecode | Beschreibung |
|---|---|
|
Ein ungültiger Parameter wurde erkannt. |
|
Nicht genügend Arbeitsspeicher verfügbar. |
|
Das E/A-Anforderungspaket (IRP-), das der parameter Request darstellt, stellt nicht genügend IO_STACK_LOCATION Strukturen bereit, damit der Treiber die Anforderung weiterleiten kann. |
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 WdfUsbTargetPipeFormatRequestForResetgefolgt von WdfRequestSend-, um eine USB-Zurücksetzungsanforderung entweder synchron oder asynchron zu senden. Alternativ können Sie die WdfUsbTargetPipeResetSynchronously 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 Zurücksetzungsanforderung abgeschlossen ist.
Wenn ein Treiber WdfRequestSendaufruft, sendet das Framework eine URB_FUNCTION_RESET_PIPE Anforderung an das E/A-Ziel. Weitere Informationen zum Zurücksetzen eines USB-Pipes finden Sie in der USB-Spezifikation.
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 erhalten hat, geben Sie das Handle der empfangenen Anforderung für den WdfUsbTargetPipeFormatRequestForReset Parameter der Request-Methode an.
Rufen Sie WdfRequestCreate auf, um eine neue E/A-Anforderung zu erstellen. Geben Sie den Anforderungshandle für den WdfUsbTargetPipeFormatRequestForReset 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 WdfUsbTargetPipeFormatRequestForReset zum Formatieren einer E/A-Anforderung muss der Treiber WdfRequestSend- aufrufen, um die Anforderung (synchron oder asynchron) an ein E/A-Ziel zu senden.
Mehrere Aufrufe von WdfUsbTargetPipeFormatRequestForResetForReset, 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), Neuformatierung (Aufruf WdfUsbTargetPipeFormatRequestForReset) und erneut senden (WdfRequestSend) jedes Anforderungsobjekt, ohne dass ein STATUS_INSUFFICIENT_RESOURCES Rückgabewert von einem späteren Aufruf an WdfRequestCreateriskiert wird. Alle nachfolgenden Aufrufe von WdfUsbTargetPipeFormatRequestForResetForReset 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.)
Informationen zum Abrufen von Statusinformationen nach Abschluss einer E/A-Anforderung finden Sie unter Abrufen von Abschlussinformationen.
Weitere Informationen zur WdfUsbTargetPipeFormatRequestForReset Methode und USB-E/A-Zielen finden Sie unter USB-E/A-Ziele.
Beispiele
Im folgenden Codebeispiel wird eine Zurücksetzungsanforderung für eine USB-Pipe formatiert, eine CompletionRoutine- Rückruffunktion registriert und die Anforderung gesendet.
status = WdfUsbTargetPipeFormatRequestForReset(
pipe,
Request
);
if (!NT_SUCCESS(status)) {
goto Exit;
}
WdfRequestSetCompletionRoutine(
Request,
AbortCompletionRoutine,
pipe
);
if (WdfRequestSend(
Request,
WdfUsbTargetPipeGetIoTarget(pipe),
WDF_NO_SEND_OPTIONS
) == FALSE) {
status = WdfRequestGetStatus(Request);
goto Exit;
}
Exit:
if (!NT_SUCCESS(status)) {
WdfRequestCompleteWithInformation(
Request,
status,
0
);
}
return;
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform- | Universal |
| Minimale KMDF-Version | 1.0 |
| Mindest-UMDF-Version | 2.0 |
| Header- | wdfusb.h (include Wdfusb.h) |
| Library | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL- | <=DISPATCH_LEVEL |
| DDI-Complianceregeln | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestForUrbXrb(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf) |