WdfUsbTargetDeviceSendControlTransferSynchronously-Funktion (wdfusb.h)
[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 WdfUsbTargetDeviceCreateWithParameters abgerufen wurde.
[in, optional] Request
Ein Handle für ein Frameworkanforderungsobjekt. Dieser Parameter ist optional und kann NULL sein. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
[in, optional] RequestOptions
Ein Zeiger auf eine vom Aufrufer zugeordnete 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 je nach gerätespezifischem Befehl entweder einen 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 sein.
Rückgabewert
WdfUsbTargetDeviceSendControlTransferSynchronously 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. |
|
Es wurde ein ungültiger Speicherdeskriptor angegeben, oder die angegebene E/A-Anforderung wurde bereits an einem E/A-Ziel in die Warteschlange gestellt. |
|
Der Treiber hat einen Timeoutwert angegeben, und die Anforderung wurde nicht innerhalb der zugewiesenen Zeit abgeschlossen. |
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 die WdfUsbTargetDeviceSendControlTransferSynchronously-Methode , um eine USB-Steuerübertragungsanforderung synchron zu senden. Um solche Anforderungen asynchron zu senden, verwenden Sie WdfUsbTargetDeviceFormatRequestForControlTransfer, gefolgt von WdfRequestSend.
Die WdfUsbTargetDeviceSendControlTransferSynchronously-Methode gibt erst zurück, wenn die Anforderung abgeschlossen ist, 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, es wird ein Fehler erkannt.
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. In beiden Fällen erfordert das Framework ein Anforderungsobjekt und je nach Typ der Steuerungsübertragung möglicherweise etwas Pufferspeicherplatz.
So leiten Sie eine E/A-Anforderung weiter, die Ihr Treiber in einer E/A-Warteschlange empfangen hat:
- Geben Sie das Handle der empfangenen Anforderung für den Request-Parameter 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 Frameworkspeicherobjekt abzurufen, das den Eingabe- oder Ausgabepuffer der Anforderung darstellt, und dieses Handle dann in der WDF_MEMORY_DESCRIPTOR Struktur platzieren, die der Treiber für den MemoryDescriptor-Parameter bereitstellt.
-
Geben Sie ein NULL-Anforderungshandle im Request-Parameter 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 WdfRequestReuse aufrufen. Mit dieser Technik kann die EvtDriverDeviceAdd-Rückruffunktion Ihres Treibers Anforderungsobjekte für ein Gerät vorab zugeordnet werden. Darüber hinaus kann ein anderer Treiberthread WdfRequestCancelSentRequest aufrufen, um die Anforderung bei Bedarf abzubrechen.
Ihr Treiber kann einen RequestOptions-Parameter ungleich NULL angeben, unabhängig davon, ob der Treiber einen Nicht-NULL- oder null-Anforderungsparameter bereitstellt. Sie können beispielsweise den Parameter RequestOptions verwenden, um einen Timeoutwert anzugeben.
-
Geben Sie Pufferspeicher für den MemoryDescriptor-Parameter der WdfUsbTargetDeviceSendControlTransferSynchronously-Methode an.
Ihr Treiber kann diesen Pufferspeicher als lokal zugeordneten Puffer, als WDFMEMORY-Handle oder als MDL angeben. Sie können die methode verwenden, die am bequemsten ist.
Falls erforderlich, konvertiert das Framework die Pufferbeschreibung in eine , die für die E/A-Zielmethode für den Zugriff auf Datenpuffer korrekt ist.
Die folgenden Techniken sind verfügbar:
-
Bereitstellen eines lokalen Puffers
Da WdfUsbTargetDeviceSendControlTransferSynchronously E/A-Anforderungen synchron verarbeitet, kann der Treiber Anforderungspuffer erstellen, die für die aufrufende Routine lokal 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 den 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 Frameworkspeicherobjekt zu erhalten, das den Puffer einer empfangenen E/A-Anforderung darstellt, wenn der Treiber den Inhalt dieses Puffers an das E/A-Ziel übergibt. Der Treiber darf die empfangene E/A-Anforderung erst abschließen, wenn die neue Anforderung, die WdfUsbTargetDeviceSendControlTransferSynchronously an das E/A-Ziel sendet, gelöscht, wiederverwendet oder neu formatiert wurde. (WdfUsbTargetDeviceSendControlTransferSynchronously erhöht die Verweisanzahl des Speicherobjekts. Durch das Löschen, Wiederverwenden oder Neuformatieren eines Anforderungsobjekts wird die Referenzanzahl des Speicherobjekts verringert.)
-
Bereitstellen einer MDL
Treiber können MDLs abrufen, die einer empfangenen E/A-Anforderung zugeordnet sind, indem sie WdfRequestRetrieveInputWdmMdl oder WdfRequestRetrieveOutputWdmMdl aufrufen.
-
Bereitstellen eines lokalen Puffers
Informationen zum Abrufen status Informationen nach Abschluss einer E/A-Anforderung finden Sie unter Abrufen von Abschlussinformationen.
Weitere Informationen zur 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 dann WdfUsbTargetDeviceSendControlTransferSynchronly aufgerufen, um eine anbieterspezifische Steuerungsü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 | Universell |
KMDF-Mindestversion | 1.0 |
UMDF-Mindestversion | 2.0 |
Kopfzeile | wdfusb.h (wdfusb.h einschließen) |
Bibliothek | 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) |
Weitere Informationen
WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unterFeedback senden und anzeigen für