WinUsb_ControlTransfer-Funktion (winusb.h)

Artikel
03/04/2024

Die WinUsb_ControlTransfer-Funktion überträgt Steuerungsdaten über einen Standard-Steuerungsendpunkt.

Syntax

BOOL WinUsb_ControlTransfer(
  [in]            WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]            WINUSB_SETUP_PACKET     SetupPacket,
  [out]           PUCHAR                  Buffer,
  [in]            ULONG                   BufferLength,
  [out, optional] PULONG                  LengthTransferred,
  [in, optional]  LPOVERLAPPED            Overlapped
);

Parameter

[in] InterfaceHandle

Ein undurchsichtiges Handle für eine Schnittstelle in der ausgewählten Konfiguration.

Um den Empfänger einer Steuerelementanforderung als das gesamte Gerät oder die erste Schnittstelle anzugeben, verwenden Sie das von WinUsb_Initialize zurückgegebene Handle. Rufen Sie für alle anderen Schnittstellen das Handle für die Zielschnittstelle ab, indem Sie WinUsb_GetAssociatedInterface aufrufen, und rufen Sie dann WinUsb_ControlTransfer auf, indem Sie das abgerufene Schnittstellenhandle angeben.

[in] SetupPacket

Das 8-Byte-Setuppaket vom Typ WINUSB_SETUP_PACKET.

[out] Buffer

Ein vom Aufrufer zugeordneter Puffer, der die zu übertragenden Daten enthält. Die Länge dieses Puffers darf 4 KB nicht überschreiten.

[in] BufferLength

Die Anzahl der zu übertragenden Bytes, ohne das Setuppaket. Diese Zahl muss kleiner oder gleich der Größe von Buffer in Bytes sein.

[out, optional] LengthTransferred

Ein Zeiger auf eine ULONG-Variable, die die tatsächliche Anzahl der übertragenen Bytes empfängt. Wenn die Anwendung während der Datenphase keine Übertragung von Daten erwartet (BufferLength ist null), kann LengthTransferredNULL sein.

[in, optional] Overlapped

Ein optionaler Zeiger auf eine OVERLAPPED-Struktur , die für asynchrone Vorgänge verwendet wird. Wenn dieser Parameter angegeben wird, gibt WinUsb_ControlTransfer sofort zurück, und das Ereignis wird signalisiert, wenn der Vorgang abgeschlossen ist. Wenn Overlapped nicht angegeben wird, überträgt die funktion WinUsb_ControlTransfer Daten synchron.

Rückgabewert

WinUsb_ControlTransfer gibt TRUE zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Routine FALSE zurück, und der Aufrufer kann den protokollierten Fehler durch Aufrufen von GetLastError abrufen.

GetLastError kann einen der folgenden Fehlercodes zurückgeben.

Rückgabecode	Beschreibung
ERROR_INVALID_HANDLE	Der Aufrufer hat NULL im Parameter InterfaceHandle übergeben.
ERROR_NOT_ENOUGH_MEMORY	Gibt an, dass nicht genügend Arbeitsspeicher zum Ausführen des Vorgangs vorhanden ist.

Hinweise

Eine Steuerungsanforderung wird immer vom Host an den Standardendpunkt eines USB-Geräts gesendet, aber der Empfänger der Anforderung kann das gesamte Gerät, eine Schnittstelle oder ein Endpunkt in der ausgewählten alternativen Einstellung sein. Im WinUsb_ControlTransfer Aufruf muss die Anwendung den Empfänger über zwei Parameter angeben: InterfaceHandle und SetupPacket.

Wenn der Empfänger einer Steuerungsanforderung das gesamte Gerät, die erste Schnittstelle oder ein beliebiger Endpunkt in dieser Schnittstelle ist, muss die Anwendung das von WinUsb_Initialize zurückgegebene Handle verwenden. Wenn der Empfänger eine andere Schnittstelle oder ihr Endpunkt ist, muss die Anwendung das WinUSB-Handle abrufen, das der Zielschnittstelle zugeordnet ist, indem sie WinUsb_GetAssociatedInterface aufruft, und dann WinUsb_ControlTransfer aufrufen, indem sie das abgerufene Schnittstellenhandle angibt.

Gemäß Abschnitt 9.3 der offiziellen USB-Spezifikation enthält das Setuptoken einer Steuerungsübertragung Informationen zur Anforderung. Für eine WinUSB-Anwendung wird dieses Setuptoken mithilfe der WINUSB_SETUP_PACKET-Struktur beschrieben.

Innerhalb des Setuptokens werden die Felder bmRequestType und wIndex verwendet, um den Empfänger der Anforderung anzugeben. Diese Felder entsprechen RequestType - bzw . Index-Membern von WINUSB_SETUP_PACKET.

Die niedrigsten zwei Bits von RequestType geben den Empfänger der Anforderung an. Der Empfänger kann das Gerät, eine Schnittstelle, ein Endpunkt oder ein anderer (für die Anforderung des Anbieters) sein. Abhängig vom Empfänger gibt das untere Byte von Index den gerätedefinierte Index des Empfängers an. Der Wert von Index hängt vom Typ der Anforderung ab. Bei Standardsteuerungsanforderungen ist der Wert beispielsweise 0 oder gibt die Schnittstellen- oder Endpunktnummer an. Für bestimmte Typen von Standardanforderungen, z. B. eine GET_DESCRIPTOR Anforderung zum Abrufen eines Zeichenfolgendeskriptors, gibt der Indexwert die Sprach-ID an.

Wenn der Empfänger das Gerät ist, muss die Anwendung RequestType - und Indexwerte festlegen. Die niedrigsten zwei Bits des RequestType-Werts müssen 0 sein. Das untere Byte des Indexwerts hängt vom Typ der Anforderung ab. InterfaceHandle muss das WinUSB-Handle sein, das von WinUsb_Initialize zurückgegeben wird.

Wenn der Empfänger der Anforderung eine Schnittstelle ist, muss die Anwendung die niedrigsten zwei Bits von RequestType auf 0x01 festlegen. Die Anwendung muss nicht das untere Byte von Index für jeden Anforderungstyp festlegen. Für Standard-, Klassen- und Anbieteranforderungen legt Winusb.sys den Wert auf die Schnittstellennummer der Zielschnittstelle fest. Die InterfaceHandle muss der Zielschnittstelle zugeordnet sein. Die Anwendung kann dieses Handle abrufen, indem sie WinUsb_GetAssociatedInterface aufruft.

Wenn der Empfänger ein Endpunkt ist, muss die Anwendung die niedrigsten zwei Bits von RequestType auf 0x02 und das untere Byte von Index auf die Endpunktadresse festlegen. In diesem Fall ist InterfaceHandle der Schnittstelle zugeordnet, die den Endpunkt enthält. Die Anwendung kann dieses Handle abrufen, indem sie WinUsb_GetAssociatedInterface aufruft.