WdfUsbTargetDeviceSendUrbSynchronly-Funktion (wdfusb.h)

Artikel
07/16/2024

[Gilt nur für KMDF]

Die WdfUsbTargetDeviceSendUrbSynchronously-Methode sendet eine USB-Anforderung synchron an ein angegebenes USB-Gerät, wobei Anforderungsparameter verwendet werden, die von einem URB-beschrieben werden.

Syntax

NTSTATUS WdfUsbTargetDeviceSendUrbSynchronously(
  [in]           WDFUSBDEVICE              UsbDevice,
  [in, optional] WDFREQUEST                Request,
  [in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [in]           PURB                      Urb
);

Parameter

[in] UsbDevice

Ein Handle für ein USB-Geräteobjekt, das aus einem vorherigen Aufruf von WdfUsbTargetDeviceCreateWithParametersabgerufen 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".

[in] Urb

Ein Zeiger auf eine aufruferinitialisierte URB--Struktur.

Wenn der zuvor WdfUsbTargetDeviceCreateWithParameters aufgerufen wurde, um UsbDevicezu erstellen, muss der Treiber WdfUsbTargetDeviceCreateUrb oder WdfUsbTargetDeviceCreateIsochUrb verwenden, um diesen URB zu erstellen.

Rückgabewert

WdfUsbTargetDeviceSendUrbSynchronly 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_INVALID_PARAMETER	Ein ungültiger Parameter wurde erkannt.
STATUS_INVALID_DEVICE_REQUEST	Die IRQL des Aufrufers war ungültig.
STATUS_INSUFFICIENT_RESOURCES	Nicht genügend Arbeitsspeicher verfügbar.
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 WdfUsbTargetDeviceSendUrbSynchronously Methode, um eine USB-Steuerübertragungsanforderung synchron zu senden. Um solche Anforderungen asynchron zu senden, verwenden Sie WdfUsbTargetDeviceFormatRequestForUrb, gefolgt von WdfRequestSend.

Die WdfUsbTargetDeviceSendUrbSynchronously-Methode wird erst zurückgegeben, wenn die Anforderung abgeschlossen wurde, es sei denn, der Treiber stellt einen Timeoutwert in der RequestOptionsWDF_REQUEST_SEND_OPTIONS-Struktur des Parameters oder sofern kein 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 den Handle der empfangenen Anforderung für den WdfUsbTargetDeviceSendUrbSynchronly Methode Request Parameter 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 zu den WdfUsbTargetDeviceSendUrbSynchronously Methode und USB-E/A-Zielen finden Sie unter USB I/O Targets.

Beispiele

Im folgenden Codebeispiel wird eine URB-Struktur initialisiert und WdfUsbTargetDeviceSendUrbSynchronouslyaufgerufen.

URB Urb;
NTSTATUS status;

Urb.UrbHeader.Function =  URB_FUNCTION_GET_CONFIGURATION;
Urb.UrbHeader.Length = sizeof(struct _URB_CONTROL_GET_CONFIGURATION_REQUEST);
Urb.UrbControlGetConfigurationRequest.TransferBufferLength = 1 ; // Must be 1
Urb.UrbControlGetConfigurationRequest.TransferBufferMDL = NULL;
Urb.UrbControlGetConfigurationRequest.TransferBuffer = outBuffer;
Urb.UrbControlGetConfigurationRequest.UrbLink = NULL;

status = WdfUsbTargetDeviceSendUrbSynchronously(
                                                UsbDevice,
                                                NULL,
                                                NULL,
                                                &Urb
                                                );

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Minimale KMDF-Version	1.0
Header-	wdfusb.h (include Wdfusb.h)
Library	Wdf01000.sys (siehe Framework-Bibliotheksversionsverwaltung.)
IRQL-	PASSIVE_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), SyncReqSend(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)