WdfUsbTargetPipeFormatRequestForAbort-Funktion (wdfusb.h)
[Gilt für KMDF und UMDF]
Die WdfUsbTargetPipeFormatRequestForAbort-Methode erstellt eine Abbruchanforderung für eine angegebene USB-Pipe, sendet die Anforderung jedoch nicht.
Syntax
NTSTATUS WdfUsbTargetPipeFormatRequestForAbort(
[in] WDFUSBPIPE Pipe,
[in] WDFREQUEST Request
);
Parameter
[in] Pipe
Ein Handle für ein Framework-Pipeobjekt, das durch Aufrufen von WdfUsbInterfaceGetConfiguredPipe abgerufen wurde.
[in] Request
Ein Handle für ein Frameworkanforderungsobjekt. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
Rückgabewert
WdfUsbTargetPipeFormatRequestForAbort gibt den Abschluss des E/A-Ziels status Wert 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. |
|
Es war nicht genügend Arbeitsspeicher verfügbar. |
|
Das vom Request-Parameter dargestellte E/A-Anforderungspaket (IRP) bietet nicht genügend IO_STACK_LOCATION Strukturen, damit der Treiber die Anforderung weiterleiten kann. |
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 WdfUsbTargetPipeFormatRequestForAbort gefolgt von WdfRequestSend, um eine USB-Abbruchanforderung entweder synchron oder asynchron zu senden. Alternativ können Sie die WdfUsbTargetPipeAbortSynchronously-Methode verwenden, um eine Anforderung synchron zu senden.
Eine USB-Abbruchanforderung bewirkt, dass das E/A-Ziel des Treibers alle E/A-Anforderungen abbricht, die an eine Pipe gesendet wurden. Wenn ein Treiber WdfRequestSend aufruft, sendet das Framework eine URB_FUNCTION_ABORT_PIPE Anforderung an das E/A-Ziel. Weitere Informationen zum Abbrechen von Vorgängen an einer USB-Pipe (auch als "Abbrechen einer Pipe" bezeichnet) finden Sie in der USB-Spezifikation.
Sie können eine E/A-Anforderung weiterleiten, die Ihr Treiber in einer E/A-Warteschlange empfangen 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 WdfUsbTargetPipeFormatRequestForAbort-Methode an.
Um eine neue E/A-Anforderung zu erstellen, rufen Sie WdfRequestCreate auf , um ein Anforderungsobjekt vorab zuzuspeichern. Geben Sie das Anforderungshandle für den Request-Parameter der WdfUsbTargetPipeFormatRequestForAbort-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 WdfUsbTargetPipeFormatRequestForAbort 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 WdfUsbTargetPipeFormatRequestForAbort , die dieselbe Anforderung verwenden, verursachen keine zusätzlichen Ressourcenzuordnungen. Aus diesem Grund kann die EvtDriverDeviceAdd-Rückruffunktion Ihres Treibers WdfRequestCreate aufrufen, um die Chance zu verringern, dass WdfRequestCreate zurückgegeben STATUS_INSUFFICIENT_RESOURCES wird, um ein oder mehrere Anforderungsobjekte für ein Gerät vorab zu verwenden. Der Treiber kann jedes Anforderungsobjekt anschließend wiederverwenden ( WdfRequestReuse aufrufen), neu formatieren ( WdfUsbTargetPipeFormatRequestForAbort aufrufen) und jedes Anforderungsobjekt erneut senden (WdfRequestSend aufrufen), ohne einen STATUS_INSUFFICIENT_RESOURCES Rückgabewert aus einem späteren Aufruf von WdfRequestCreate zu riskieren. Alle nachfolgenden Aufrufe von WdfUsbTargetPipeFormatRequestForAbort 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 zugeordnet.)
Informationen zum Abrufen status Informationen nach Abschluss einer E/A-Anforderung finden Sie unter Abrufen von Abschlussinformationen.
Weitere Informationen zur WdfUsbTargetPipeFormatRequestForAbort-Methode und USB-E/A-Zielen finden Sie unter USB-E/A-Ziele.
Beispiele
Im folgenden Codebeispiel wird eine Abbruchanforderung für eine USB-Pipe formatiert, eine CompletionRoutine-Rückruffunktion registriert und die Anforderung gesendet.
status = WdfUsbTargetPipeFormatRequestForAbort(
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 | Universell |
| KMDF-Mindestversion | 1.0 |
| UMDF-Mindestversion | 2.0 |
| Kopfzeile | wdfusb.h (wdfusb.h einschließen) |
| Bibliothek | 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) |