funzione USBD_SelectConfigUrbAllocateAndBuild (usbdlib.h)

Articolo
02/27/2024

La routine USBD_SelectConfigUrbAllocateAndBuild alloca e formatta una struttura URB necessaria per selezionare una configurazione per un dispositivo USB.

Nota In Windows 8 USBD_SelectConfigUrbAllocateAndBuild sostituisce USBD_CreateConfigurationRequestEx e USBD_CreateConfigurationRequest.

Sintassi

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

Parametri

[in] USBDHandle

Handle USBD recuperato dal driver client in una chiamata precedente alla routine di USBD_CreateHandle .

[in] ConfigurationDescriptor

Puntatore a una struttura di USB_CONFIGURATION_DESCRIPTOR allocata dal chiamante che contiene il descrittore di configurazione per la configurazione da selezionare. In genere, il driver client invia un'ISTANZA del tipo URB_FUNCTION_GET_DESCRIPTOR_FROM_DEVICE (vedere _URB_CONTROL_DESCRIPTOR_REQUEST) per recuperare informazioni su configurazioni, interfacce, endpoint, fornitori e descrittori specifici della classe da un dispositivo USB. Quando il driver client specifica USB_CONFIGURATION_DESCRIPTOR_TYPE come tipo descrittore, la richiesta recupera tutte le informazioni sul dispositivo in una struttura USB_CONFIGURATION_DESCRIPTOR . Il driver passa quindi il puntatore ricevuto alla struttura USB_CONFIGURATION_DESCRIPTOR nel parametro ConfigurationDescriptor .

[in] InterfaceList

Puntatore al primo elemento di una matrice allocata dal chiamante di strutture USBD_INTERFACE_LIST_ENTRY . La lunghezza della matrice dipende dal numero di interfacce nel descrittore di configurazione. Per altre informazioni, vedere la sezione Osservazioni.

[out] Urb

Puntatore a unastrutturaae che che riceve l'ASSEGNAZIONE DELL'ASSEGNARE DALL'USBD_SelectConfigUrbAllocateAndBuild. Il driver client deve liberare IL DRIVER al termine dell'uso del driver chiamando USBD_UrbFree.

Valore restituito

La routine USBD_SelectConfigUrbAllocateAndBuild restituisce un codice di stato NT.

I valori possibili includono, ma non sono limitati a, i codici di stato elencati nella tabella seguente.

Codice restituito	Descrizione
STATUS_SUCCESS	La richiesta è stata completata.
STATUS_INVALID_PARAMETER	Il chiamante ha passato un valore di parametro non valido. USBDHandle o Urb è NULL.
STATUS_INSUFFICIENT_RESOURCES	Memoria insufficiente disponibile per completare la richiesta.

Commenti

Prima di chiamare USBD_SelectConfigUrbAllocateAndBuild, il driver client deve eseguire le attività seguenti:

Ottenere il numero di interfacce nella configurazione. Queste informazioni sono contenute nel membro bNumInterfaces della struttura USB_CONFIGURATION_DESCRIPTOR a cui punta ConfigurationDescriptor.
Creare una matrice di strutture USBD_INTERFACE_LIST_ENTRY . Il numero di elementi nella matrice deve essere uno più del numero di interfacce. Inizializzare la matrice chiamando RtlZeroMemory.
Ottenere un descrittore dell'interfaccia per ogni interfaccia (o la relativa impostazione alternativa) nella configurazione. È possibile ottenere tali descrittori di interfaccia chiamando USBD_ParseConfigurationDescriptorEx.
Per ogni elemento (ad eccezione dell'ultimo elemento) nella matrice, impostare il membro InterfaceDescriptor sull'indirizzo di un descrittore di interfaccia. Per il primo elemento della matrice, impostare il membro InterfaceDescriptor sull'indirizzo del descrittore dell'interfaccia che rappresenta la prima interfaccia nella configurazione. Analogamente per l'elemento nnella matrice, impostare il membro InterfaceDescriptor sull'indirizzo del descrittore dell'interfaccia che rappresenta l'nainterfaccia nella configurazione.
Il membro InterfaceDescriptor dell'ultimo elemento deve essere impostato su NULL.

USBD_SelectConfigUrbAllocateAndBuild esegue le attività seguenti:

Crea un oggetto URB e lo riempie con informazioni sulla configurazione specificata, sulle relative interfacce ed endpoint e imposta il tipo di richiesta su URB_FUNCTION_SELECT_CONFIGURATION.
Riempie una struttura USBD_INTERFACE_INFORMATION nell'AREA DI AMMINISTRAZIONE per ogni interfaccia.
Imposta il membro Interfacedell'elemento ndel chiamante fornito USBD_INTERFACE_LIST_ENTRY matrice all'indirizzo della struttura di USBD_INTERFACE_INFORMATION corrispondente nell'OGGETTO.

È possibile usare il puntatore ricevuto allastrutturaae per per inviare una richiesta di configurazione selezionata allo stack di driver USB per impostare la configurazione specificata. È inoltre possibile usare il membro Interface di ogni struttura USBD_INTERFACE_INFORMATION nella matrice per ottenere informazioni sull'interfaccia. All'interno di ogni struttura USBD_INTERFACE_INFORMATION , il membro Pipe è una matrice di strutture USBD_PIPE_INFORMATION . Ogni USBD_PIPE_INFORMATION struttura contiene informazioni sulle pipe aperte (dallo stack di driver USB) per gli endpoint di tale interfaccia. È possibile ottenere handle pipe dalla matrice e archiviarli per le richieste di I/O future al dispositivo.

Requisiti

Requisito	Valore
Client minimo supportato	Richiede WDK per Windows 8. Destinazione Windows Vista e versioni successive del sistema operativo Windows.
Piattaforma di destinazione	Desktop
Intestazione	usbdlib.h
Libreria	Usbdex.lib
IRQL	DISPATCH_LEVEL

Vedi anche

USBD_CreateConfigurationRequestEx

USBD_CreateHandle

Condividi tramite