WdfUsbTargetDeviceSendControlTransferSynchronously-Funktion (wdfusb.h)

Artikel
07/16/2024

[Gilt für KMDF und UMDF]

Die WdfUsbTargetDeviceSendControlTransferSynchronously Methode erstellt eine USB-Steuerungsübertragungsanforderung und sendet sie synchron an ein E/A-Ziel.

Syntax

NTSTATUS WdfUsbTargetDeviceSendControlTransferSynchronously(
  [in]            WDFUSBDEVICE                  UsbDevice,
  [in, optional]  WDFREQUEST                    Request,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS     RequestOptions,
  [in]            PWDF_USB_CONTROL_SETUP_PACKET SetupPacket,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR        MemoryDescriptor,
  [out, optional] PULONG                        BytesTransferred
);

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] SetupPacket

Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_USB_CONTROL_SETUP_PACKET Struktur, die die Steuerungsübertragung beschreibt.

[in, optional] MemoryDescriptor

Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_MEMORY_DESCRIPTOR Struktur, die abhängig vom gerätespezifischen Befehl entweder eine Eingabe oder einen Ausgabepuffer beschreibt. Dieser Zeiger ist optional und kann NULL-sein. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[out, optional] BytesTransferred

Ein Zeiger auf einen Speicherort, der die Anzahl der übertragenen Bytes empfängt. Dieser Parameter ist optional und kann NULL-werden.

Rückgabewert

WdfUsbTargetDeviceSendControlTransferSynchronously gibt den Fertigstellungsstatuswert 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_INSUFFICIENT_RESOURCES	Nicht genügend Arbeitsspeicher verfügbar.
STATUS_INVALID_DEVICE_REQUEST	Es wurde ein ungültiger Speicherdeskriptor angegeben, 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 WdfUsbTargetDeviceSendControlTransferSynchronously Methode, um eine USB-Steuerungsübertragungsanforderung synchron zu senden. Um solche Anforderungen asynchron zu senden, verwenden Sie WdfUsbTargetDeviceFormatRequestForControlTransfer, gefolgt von WdfRequestSend.

Die WdfUsbTargetDeviceSendControlTransferSynchronously--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. In beiden Fällen erfordert das Framework ein Anforderungsobjekt und abhängig vom Typ der Steuerungsübertragung möglicherweise einen Pufferraum.

So leiten Sie eine E/A-Anforderung weiter, die Ihr Treiber in einer E/A-Warteschlange erhalten hat:

Geben Sie das Handle der empfangenen Anforderung für den Parameter Request an.
Verwenden Sie den Eingabe- oder Ausgabepuffer der empfangenen Anforderung für den MemoryDescriptor Parameter.
Der Treiber kann WdfRequestRetrieveInputMemory oder WdfRequestRetrieveOutputMemory- aufrufen, um ein Handle für ein Framework-Speicherobjekt abzurufen, das den Eingabe- oder Ausgabepuffer der Anforderung darstellt, und dann das Handle in der WDF_MEMORY_DESCRIPTOR Struktur platzieren, die der Treiber für den MemoryDescriptor Parameter bereitstellt.

So erstellen und senden Sie eine neue Anforderung:

Geben Sie einen NULL- Anforderungshandle im 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.
Stellen Sie Pufferraum für den WdfUsbTargetDeviceSendControlTransferSynchronouslyMemoryDescriptor Parameter der Methode bereit.
Der Treiber kann diesen Pufferspeicher als lokal zugewiesenen Puffer, als WDFMEMORY-Handle oder als MDL angeben. Sie können verwenden, welche Methode am bequemsten ist.

Bei Bedarf konvertiert das Framework die Pufferbeschreibung in eine, die für die -Methode des E/A-Ziels für den Zugriff auf Datenpufferkorrekt ist.

Die folgenden Techniken sind verfügbar:
- Bereitstellen eines lokalen Puffers
  Da WdfUsbTargetDeviceSendControlTransferSynchronously E/A-Anforderungen synchron verarbeitet, kann der Treiber Anforderungspuffer erstellen, die lokal für die aufrufende Routine sind, wie im folgenden Codebeispiel gezeigt.
```
WDF_MEMORY_DESCRIPTOR  memoryDescriptor;
MY_BUFFER_TYPE  myBuffer;
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&memoryDescriptor,
                                  (PVOID) &myBuffer,
                                  sizeof(myBuffer));
```
- Bereitstellen eines WDFMEMORY-Handles
  Rufen Sie WdfMemoryCreate oder WdfMemoryCreatePreallocated auf, um ein Handle für vom Framework verwalteten Speicher abzurufen, wie im folgenden Codebeispiel gezeigt.
```
WDF_MEMORY_DESCRIPTOR  memoryDescriptor;
WDFMEMORY  memoryHandle = NULL;
status = WdfMemoryCreate(NULL,
                         NonPagedPool,
                         POOL_TAG,
                         MY_BUFFER_SIZE,
                         &memoryHandle,
                         NULL);
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(&memoryDescriptor,
                                  memoryHandle,
                                  NULL);
```
  Alternativ kann der Treiber WdfRequestRetrieveInputMemory oder WdfRequestRetrieveOutputMemory- aufrufen, um ein Handle für ein Framework-Speicherobjekt abzurufen, das den Puffer einer empfangenen E/A-Anforderung darstellt, wenn der Treiber den Inhalt dieses Puffers an das E/A-Ziel übergeben soll. Der Treiber darf die empfangene E/A-Anforderung erst abschließen, wenn die neue Anforderung, die WdfUsbTargetDeviceSendControlTransferSynchronously sendet, an das E/A-Ziel gesendet wurde, gelöscht, wiederverwendet oder neu formatiert wurde. (WdfUsbTargetDeviceSendControlTransferSynchronously erhöht die Referenzanzahl des Speicherobjekts. Beim Löschen, Erneuten Verwenden oder Neuformatieren eines Anforderungsobjekts wird die Referenzanzahl des Speicherobjekts erhöht.)
- Bereitstellen einer MDL
  Treiber können MDLs abrufen, die einer empfangenen E/A-Anforderung zugeordnet sind, indem sie WdfRequestRetrieveInputWdmMdl oder WdfRequestRetrieveOutputWdmMdlaufrufen.

Das Framework legt das USBD_SHORT_TRANSFER_OK Flag in seiner internen URB-fest. Durch Festlegen dieses Flags kann das letzte Paket einer Datenübertragung kleiner als die maximale Paketgröße sein.

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

Weitere Informationen zu den WdfUsbTargetDeviceSendControlTransferSynchronously Methode und USB-E/A-Zielen finden Sie unter USB-E/A-Ziele.

Beispiele

Im folgenden Codebeispiel wird eine WDF_USB_CONTROL_SETUP_PACKET Struktur initialisiert und anschließend WdfUsbTargetDeviceSendControlTransferSynchronly aufgerufen, um eine anbieterspezifische Steuerelementübertragung zu senden.

WDF_USB_CONTROL_SETUP_PACKET  controlSetupPacket;

WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR(
                                         &controlSetupPacket,
                                         BmRequestHostToDevice,
                                         BmRequestToDevice,
                                         USBFX2LK_REENUMERATE,
                                         0,
                                         0
                                         );

status = WdfUsbTargetDeviceSendControlTransferSynchronously(
                                         UsbDevice,
                                         WDF_NO_HANDLE,
                                         NULL,
                                         &controlSetupPacket,
                                         NULL,
                                         NULL
                                         );
return status;

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), RequestForUrbXrb(kmdf), SyncReqSend(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)