WdfUsbTargetPipeResetSynchronously-Funktion (wdfusb.h)
[Gilt für KMDF und UMDF]
Die WdfUsbTargetPipeResetSynchronously Methode erstellt eine Zurücksetzungsanforderung und sendet sie synchron an eine angegebene USB-Pipe.
Syntax
NTSTATUS WdfUsbTargetPipeResetSynchronously(
[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
WdfUsbTargetPipeResetSynchronously gibt den Abschlussstatuswert 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 |
|---|---|
|
Die Größe der WDF_REQUEST_SEND_OPTIONS Struktur, die vom angegebenen RequestOptions- Parameter falsch war. |
|
Ein ungültiger Parameter wurde erkannt. |
|
Nicht genügend Arbeitsspeicher verfügbar. |
|
Die IRQL des Aufrufers wurde nicht PASSIVE_LEVEL, oder die E/A-Anforderung, dass der angegebene Request Parameter bereits an ein E/A-Ziel in die Warteschlange gestellt wurde. |
|
Der Treiber hat einen Timeoutwert angegeben, und die Anforderung wurde nicht innerhalb der zugewiesenen Zeit abgeschlossen. |
|
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 die WdfUsbTargetPipeResetSynchronously Methode, um eine USB-Zurücksetzungsanforderung synchron zu senden. Um solche Anforderungen asynchron zu senden, verwenden Sie WdfUsbTargetPipeFormatRequestForResetgefolgt von WdfRequestSend.
Bevor das Framework das USB-Pipe des E/A-Ziels zurücksetzt, werden alle E/A-Anforderungen abgebrochen, die in der E/A-Zielwarteschlange verbleiben. Der Treiber darf erst dann zusätzliche E/A-Anforderungen an das E/A-Ziel senden, wenn WdfUsbTargetPipeResetSynchronously zurückgegeben wird.
Der Treiber muss WdfIoTargetStop- aufrufen, bevor er WdfUsbTargetPipeResetSynchronouslyaufruft. Nachdem WdfUsbTargetPipeResetSynchronously zurückgegeben wurde, kann der Treiber WdfIoTargetStartaufrufen.
Wenn ein Treiber WdfUsbTargetPipeResetSynchronouslyaufruft, 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.
Die WdfUsbTargetPipeResetSynchronously Methode wird erst zurückgegeben, wenn die Anforderung abgeschlossen wurde, es sei denn, der Treiber stellt einen Timeoutwert in der WDF_REQUEST_SEND_OPTIONS-Struktur bereit, auf die der RequestOptions Parameter verweist, oder es sei denn, ein Fehler wird erkannt.
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 den Handle der empfangenen Anforderung für den WdfUsbTargetPipeResetSynchronously -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.
Informationen zum Abrufen von Statusinformationen nach Abschluss einer E/A-Anforderung finden Sie unter Abrufen von Abschlussinformationen.
Weitere Informationen zur WdfUsbTargetPipeResetSynchronously Methode und USB-E/A-Zielen finden Sie unter USB-E/A-Ziele.
Beispiele
Im folgenden Codebeispiel wird eine Rücksetzanforderung an die Pipe eines USB-Geräts gesendet.
NTSTATUS status;
status = WdfUsbTargetPipeResetSynchronously(
Pipe,
WDF_NO_HANDLE,
NULL
);
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) |