Funzione WdfUsbTargetDeviceRetrieveConfigDescriptor (wdfusb.h)

Articolo
02/27/2024

[Si applica a KMDF e UMDF]

Il metodo WdfUsbTargetDeviceRetrieveConfigDescriptor recupera il descrittore di configurazione USB per il dispositivo USB associato a un oggetto dispositivo USB framework specificato.

Sintassi

NTSTATUS WdfUsbTargetDeviceRetrieveConfigDescriptor(
  [in]      WDFUSBDEVICE UsbDevice,
  [out]     PVOID        ConfigDescriptor,
  [in, out] PUSHORT      ConfigDescriptorLength
);

Parametri

[in] UsbDevice

Handle per un oggetto dispositivo USB ottenuto da una chiamata precedente a WdfUsbTargetDeviceCreateWithParameters.

[out] ConfigDescriptor

Puntatore a un buffer allocato dal chiamante che riceve una struttura USB_CONFIGURATION_DESCRIPTOR , seguita da una o più strutture USB_INTERFACE_DESCRIPTOR e USB_ENDPOINT_DESCRIPTOR . Questo parametro è facoltativo e può essere NULL, nel qual caso WdfUsbTargetDeviceRetrieveConfigDescriptor restituisce la lunghezza del buffer richiesta. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[in, out] ConfigDescriptorLength

Puntatore a una posizione che fornisce la lunghezza del buffer a cui punta ConfigDescriptor . Se il puntatore fornito per ConfigDescriptor è NULL, WdfUsbTargetDeviceRetrieveConfigDescriptor restituisce la lunghezza del buffer richiesta nella posizione a cui punta ConfigDescriptorLength.

Valore restituito

WdfUsbTargetDeviceRetrieveConfigDescriptor restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo può restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_DEVICE_STATE	Un descrittore di configurazione non è disponibile per la destinazione specificata.
STATUS_INVALID_PARAMETER	È stato rilevato un parametro non valido.
STATUS_BUFFER_TOO_SMALL	Le dimensioni del buffer specificate sono troppo piccole per i dati o il chiamante ha fornito NULL per il parametro ConfigDescriptor .

Questo metodo potrebbe anche restituire altri valori NTSTATUS.

Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.

Commenti

Il metodo WdfUsbTargetDeviceRetrieveConfigDescriptor recupera tutte le informazioni di configurazione del dispositivo USB specificato, ovvero il descrittore di configurazione più eventuali descrittori di interfaccia o endpoint che potrebbero essere presenti. Per informazioni sul formato di queste informazioni, vedere la specifica USB.

È possibile usare WdfUsbTargetDeviceSelectConfig per selezionare solo la prima configurazione USB elencata nell'elenco dei descrittori, ma è possibile selezionare più interfacce all'interno di questa singola configurazione.

I driver devono chiamare due volte WdfUsbTargetDeviceRetrieveConfigDescriptor , come indicato di seguito:

Impostare il puntatore ConfigDescriptor su NULL, in modo che WdfUsbTargetDeviceRetrieveConfigDescriptor restituisca le dimensioni del buffer necessarie nell'indirizzo su cui ConfigDescriptorLength punta.
Allocare spazio buffer per contenere le informazioni di configurazione. Ad esempio, un driver potrebbe chiamare ExAllocatePoolWithTag per allocare un buffer oppure chiamare WdfMemoryCreate per creare un oggetto memoria del framework.
Chiamare di nuovo WdfUsbTargetDeviceRetrieveConfigDescriptor , passandolo un puntatore al nuovo buffer e alle dimensioni del buffer.

Dopo la seconda chiamata a WdfUsbTargetDeviceRetrieveConfigDescriptor , il buffer a cui punta ConfigDescriptor contiene una struttura USB_CONFIGURATION_DESCRIPTOR , seguita da una o più strutture USB_INTERFACE_DESCRIPTOR e USB_ENDPOINT_DESCRIPTOR . Queste ultime strutture sono disposte nell'ordine descritto nella specifica USB.

Per altre informazioni sul metodo WdfUsbTargetDeviceRetrieveConfigDescriptor e sulle destinazioni di I/O USB, vedere Destinazioni di I/O USB.

Esempio

L'esempio di codice seguente chiama WdfUsbTargetDeviceRetrieveConfigDescriptor per ottenere le dimensioni del buffer necessarie, chiama WdfMemoryCreate per creare un oggetto e un buffer di memoria e quindi chiama nuovamente WdfUsbTargetDeviceRetrieveConfigDescriptor per ottenere le informazioni di configurazione di un dispositivo.

USHORT  size;
NTSTATUS  ntStatus;
PMY_DEVICE_CONTEXT  myDeviceContext;
PUSB_CONFIGURATION_DESCRIPTOR  configurationDescriptor = NULL;
WDF_OBJECT_ATTRIBUTES  objectAttribs;
WDFMEMORY  memoryHandle;

myDeviceContext = GetDeviceContext(Device);

ntStatus = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                            myDeviceContext->WdfUsbTargetDevice,
                                            NULL,
                                            &size
                                            );

if (ntStatus != STATUS_BUFFER_TOO_SMALL) {
    return ntStatus;
}

WDF_OBJECT_ATTRIBUTES_INIT(&objectAttribs);
objectAttribs.ParentObject = myDeviceContext->WdfUsbTargetDevice;

ntStatus = WdfMemoryCreate(
                           &objectAttribs,
                           NonPagedPool,
                           POOL_TAG,
                           size,
                           &memoryHandle,
                           (PVOID)&configurationDescriptor
                           );
if (!NT_SUCCESS(ntStatus)) {
    return ntStatus;
}

ntStatus = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                            myDeviceContext->WdfUsbTargetDevice,
                                            configurationDescriptor,
                                            &size
                                            );
if (!NT_SUCCESS(ntStatus)) {
    return ntStatus;
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1,0
Versione UMDF minima	2,0
Intestazione	wdfusb.h (include Wdfusb.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)