WdfUsbTargetPipeAbortSynchronously-Funktion (wdfusb.h)

Artikel
07/16/2024

[Gilt für KMDF und UMDF]

Die WdfUsbTargetPipeAbortSynchronously Methode erstellt eine abgebrochene Anforderung und sendet sie synchron an eine angegebene USB-Pipe.

Syntax

NTSTATUS WdfUsbTargetPipeAbortSynchronously(
  [in]           WDFUSBPIPE                Pipe,
  [in, optional] WDFREQUEST                Request,
  [in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions
);

Parameter

[in] Pipe

Ein Handle zu einem Framework-Pipeobjekt, das durch Aufrufen WdfUsbInterfaceGetConfiguredPipeabgerufen wurde.

[in, optional] Request

Ein Handle zu einem Framework-Anforderungsobjekt. Dieser Parameter ist optional und kann NULL-werden. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in, optional] RequestOptions

Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_REQUEST_SEND_OPTIONS Struktur, die Optionen für die Anforderung angibt. Dieser Zeiger ist optional und kann NULL-sein. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

Rückgabewert

WdfUsbTargetPipeAbortSynchronously gibt den Abschlussstatuswert des E/A-Ziels zurück, wenn der Vorgang erfolgreich ist. Andernfalls kann diese Methode einen der folgenden Werte zurückgeben:

Rückgabecode	Beschreibung
STATUS_INFO_LENGTH_MISMATCH	Die Größe der WDF_REQUEST_SEND_OPTIONS Struktur, die vom angegebenen RequestOptions- Parameter falsch war.
STATUS_INVALID_PARAMETER	Ein ungültiger Handle wurde erkannt.
STATUS_INSUFFICIENT_RESOURCES	Nicht genügend Arbeitsspeicher verfügbar.
STATUS_INVALID_DEVICE_REQUEST	Die IRQL des Anrufers wurde nicht PASSIVE_LEVEL, oder die angegebene E/A-Anforderung wurde bereits an ein E/A-Ziel in die Warteschlange gestellt.
STATUS_IO_TIMEOUT	Der Treiber hat einen Timeoutwert angegeben, und die Anforderung wurde nicht innerhalb der zugewiesenen Zeit abgeschlossen.

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 die WdfUsbTargetPipeAbortSynchronously Methode, um eine USB-Abbruchanforderung synchron zu senden. Um solche Anforderungen asynchron zu senden, verwenden Sie WdfUsbTargetPipeFormatRequestForAbortgefolgt von WdfRequestSend.

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 WdfUsbTargetPipeAbortSynchronouslyaufruft, sendet das Framework eine URB_FUNCTION_ABORT_PIPE Anforderung an das E/A-Ziel. Weitere Informationen zum Abbrechen von Vorgängen in einem USB-Rohr (auch als "Abbruch einer Pfeife" bezeichnet) finden Sie in der USB-Spezifikation.

Die WdfUsbTargetPipeAbortSynchronously Methode wird erst zurückgegeben, wenn die Anforderung abgeschlossen wurde, es sei denn, der Treiber stellt einen Timeoutwert in der WDF_REQUEST_SEND_OPTIONS RequestOptions Parameterstruktur oder außer wenn ein Fehler erkannt wird.

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 WdfUsbTargetPipeAbortSynchronously Parameter der Request-Methode an.

Um eine neue Anforderung zu erstellen und zu senden, geben Sie entweder ein NULL- Anforderungshandle für den Parameter Request an, oder erstellen Sie ein neues Anforderungsobjekt, und geben Sie dessen Handle an:

Wenn Sie ein NULL- Anforderungshandle bereitstellen, verwendet das Framework ein internes Anforderungsobjekt. Diese Technik ist einfach zu verwenden, aber der Treiber kann die Anforderung nicht abbrechen.
Wenn Sie WdfRequestCreate aufrufen, um ein oder mehrere Anforderungsobjekte zu erstellen, können Sie diese Anforderungsobjekte wiederverwenden, indem Sie WdfRequestReuseaufrufen. Mit dieser Technik können Sie die EvtDriverDeviceAdd Rückruffunktion Ihres Treibers vorschreiben, um Anforderungsobjekte für ein Gerät vorab zu verwenden. Darüber hinaus kann ein anderer Treiberthread WdfRequestCancelSentRequest- aufrufen, um die Anforderung bei Bedarf abzubrechen.

Der Treiber kann einen Parameter ohneNULL-RequestOptions- angeben, unabhängig davon, ob der Treiber ein nicht-NULL- oder ein NULL-Request Parameter bereitstellt. Sie können z. B. den parameter RequestOptions verwenden, um einen Timeoutwert anzugeben.

Informationen zum Abrufen von Statusinformationen nach Abschluss einer E/A-Anforderung finden Sie unter Abrufen von Abschlussinformationen.

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

Beispiele

Im folgenden Codebeispiel werden Abbruchanforderungen an alle Rohre gesendet, die für die Schnittstelle eines USB-Geräts konfiguriert sind.

UCHAR  i;
ULONG  count;
NTSTATUS  status;
PDEVICE_CONTEXT  pDevContext;

pDevContext = GetDeviceContext(Device);

count = WdfUsbInterfaceGetNumConfiguredPipes(
                                             pDevContext->UsbInterface
                                             );

for (i = 0; i < count; i++) {
    WDFUSBPIPE pipe;

    pipe = WdfUsbInterfaceGetConfiguredPipe(
                                            pDevContext->UsbInterface,
                                            i,
                                            NULL
                                            );
    status = WdfUsbTargetPipeAbortSynchronously(
                                                pipe,
                                                WDF_NO_HANDLE,
                                                NULL
                                                );
    if (!NT_SUCCESS(status)) {
        break;
    }
}

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-	PASSIVE_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), AnforderungForUrbXrb(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

Siehe auch

WdfRequestCancelSentRequest

WdfUsbTargetPipeResetSynchronously

Freigeben über