USBD_SelectConfigUrbAllocateAndBuild-Funktion (usbdlib.h)

Artikel
02/29/2024

Die USBD_SelectConfigUrbAllocateAndBuild Routine ordnet und formatiert eine URB-Struktur , die erforderlich ist, um eine Konfiguration für ein USB-Gerät auszuwählen.

Hinweis In Windows 8 ersetzt USBD_SelectConfigUrbAllocateAndBuildUSBD_CreateConfigurationRequestEx und USBD_CreateConfigurationRequest.

Syntax

NTSTATUS USBD_SelectConfigUrbAllocateAndBuild(
  [in]  USBD_HANDLE                   USBDHandle,
  [in]  PUSB_CONFIGURATION_DESCRIPTOR ConfigurationDescriptor,
  [in]  PUSBD_INTERFACE_LIST_ENTRY    InterfaceList,
  [out] PURB                          *Urb
);

Parameter

[in] USBDHandle

USBD-Handle, das vom Clienttreiber in einem vorherigen Aufruf der USBD_CreateHandle-Routine abgerufen wird.

[in] ConfigurationDescriptor

Zeiger auf eine vom Aufrufer zugeordnete USB_CONFIGURATION_DESCRIPTOR Struktur, die den Konfigurationsdeskriptor für die auszuwählende Konfiguration enthält. In der Regel übermittelt der Clienttreiber eine URB vom Typ URB_FUNCTION_GET_DESCRIPTOR_FROM_DEVICE (siehe _URB_CONTROL_DESCRIPTOR_REQUEST), um Informationen zu Konfigurationen, Schnittstellen, Endpunkten, dem Anbieter und klassenspezifischen Deskriptoren von einem USB-Gerät abzurufen. Wenn der Clienttreiber USB_CONFIGURATION_DESCRIPTOR_TYPE als Deskriptortyp angibt, ruft die Anforderung alle Geräteinformationen in einer USB_CONFIGURATION_DESCRIPTOR-Struktur ab. Der Treiber übergibt dann den empfangenen Zeiger auf die USB_CONFIGURATION_DESCRIPTOR-Struktur im ConfigurationDescriptor-Parameter .

[in] InterfaceList

Zeiger auf das erste Element eines aufruferseitig zugewiesenen Arrays von USBD_INTERFACE_LIST_ENTRY Strukturen. Die Länge des Arrays hängt von der Anzahl der Schnittstellen im Konfigurationsdeskriptor ab. Weitere Informationen finden Sie in den Hinweisen.

[out] Urb

Zeiger auf eine URB-Struktur , die die von USBD_SelectConfigUrbAllocateAndBuild zugeordnete URB empfängt. Der Clienttreiber muss die URB freigeben, wenn der Treiber die Verwendung durch aufruft USBD_UrbFree.

Rückgabewert

Die USBD_SelectConfigUrbAllocateAndBuild-Routine gibt einen NT-status-Code zurück.

Mögliche Werte sind unter anderem die in der folgenden Tabelle aufgeführten status Codes.

Rückgabecode	Beschreibung
STATUS_SUCCESS	Die Anforderung wurde erfolgreich gesendet.
STATUS_INVALID_PARAMETER	Der Aufrufer hat einen ungültigen Parameterwert übergeben. USBDHandle oder Urb ist NULL.
STATUS_INSUFFICIENT_RESOURCES	Unzureichender Arbeitsspeicher, um die Anforderung abzuschließen.

Hinweise

Vor dem Aufrufen USBD_SelectConfigUrbAllocateAndBuild muss der Clienttreiber die folgenden Aufgaben ausführen:

Rufen Sie die Anzahl der Schnittstellen in der Konfiguration ab. Diese Informationen sind im bNumInterfaces-Member der USB_CONFIGURATION_DESCRIPTOR-Struktur enthalten, auf die configurationDescriptor verweist.
Erstellen Sie ein Array von USBD_INTERFACE_LIST_ENTRY Strukturen. Die Anzahl der Elemente im Array muss um eins größer sein als die Anzahl der Schnittstellen. Initialisieren Sie das Array, indem Sie RtlZeroMemory aufrufen.
Rufen Sie einen Schnittstellendeskriptor für jede Schnittstelle (oder deren alternative Einstellung) in der Konfiguration ab. Sie können diese Schnittstellendeskriptoren abrufen, indem Sie USBD_ParseConfigurationDescriptorEx aufrufen.
Legen Sie für jedes Element (mit Ausnahme des letzten Elements) im Array den Member InterfaceDescriptor auf die Adresse eines Schnittstellendeskriptors fest. Legen Sie für das erste Element im Array den Member InterfaceDescriptor auf die Adresse des Schnittstellendeskriptors fest, der die erste Schnittstelle in der Konfiguration darstellt. Legen Sie für das nth-Element im Array den Member InterfaceDescriptor auf die Adresse des Schnittstellendeskriptors fest, der die n-tenSchnittstelle in der Konfiguration darstellt.
Das InterfaceDescriptor-Element des letzten Elements muss auf NULL festgelegt werden.

USBD_SelectConfigUrbAllocateAndBuild führt die folgenden Aufgaben aus:

Erstellt eine URB und füllt sie mit Informationen zur angegebenen Konfiguration, ihren Schnittstellen und Endpunkten und legt den Anforderungstyp auf URB_FUNCTION_SELECT_CONFIGURATION fest.
Füllt eine USBD_INTERFACE_INFORMATION-Struktur in der URB für jede Schnittstelle aus.
Legt den Interface-Member des nth-Elements des vom Aufrufer bereitgestellten USBD_INTERFACE_LIST_ENTRY Arrays auf die Adresse der entsprechenden USBD_INTERFACE_INFORMATION-Struktur in der URB fest.

Sie können den empfangenen Zeiger auf die URB-Struktur verwenden, um eine Auswahlkonfigurationsanforderung an den USB-Treiberstapel zu senden, um die angegebene Konfiguration festzulegen. Darüber hinaus können Sie den Schnittstellenmember jeder USBD_INTERFACE_INFORMATION Struktur im Array verwenden, um Informationen zur Schnittstelle abzurufen. Innerhalb jeder USBD_INTERFACE_INFORMATION-Struktur ist das Pipes-Element ein Array von USBD_PIPE_INFORMATION Strukturen. Jede USBD_PIPE_INFORMATION-Struktur enthält Informationen zu den Pipes, die (vom USB-Treiberstapel) für die Endpunkte in dieser Schnittstelle geöffnet werden. Sie können Pipehandles aus dem Array abrufen und sie für zukünftige E/A-Anforderungen an das Gerät speichern.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Erfordert WDK für Windows 8. Zielt auf Windows Vista und höhere Versionen des Windows-Betriebssystems ab.
Zielplattform	Desktop
Kopfzeile	usbdlib.h
Bibliothek	Usbdex.lib
IRQL	DISPATCH_LEVEL

Weitere Informationen

USBD_CreateConfigurationRequestEx

USBD_CreateHandle

Share via