Funzione WdfUsbTargetDeviceRetrieveConfigDescriptor (wdfusb.h)

Articolo
02/07/2025

[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 altre informazioni, vedere la sezione Osservazioni seguente.

[in, out] ConfigDescriptorLength

Puntatore a una posizione che fornisce la lunghezza del buffer a cui ConfigDescriptor punta. Se il puntatore fornito per ConfigDescriptor è NULL, WdfUsbTargetDeviceRetrieveConfigDescriptor restituisce la lunghezza del buffer necessaria 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 era 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.

Osservazioni

Il metodo WdfUsbTargetDeviceRetrieveConfigDescriptor recupera tutte le informazioni di configurazione del dispositivo USB specificato, ovvero il descrittore di configurazione più qualsiasi descrittore di interfaccia o endpoint che potrebbe essere presente. 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 WdfUsbTargetDeviceRetrieveConfigDescriptor due volte, come indicato di seguito:

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

Dopo la seconda chiamata a WdfUsbTargetDeviceRetrieveConfigDescriptor restituisce, 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 metodo e destinazioni I/O USB, vedere Destinazioni I/O USB.

Esempi

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 WdfUsbTargetDeviceRetrieveConfigDescriptor per ottenere nuovamente 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;
}

Fabbisogno

Requisito	Valore
piattaforma di destinazione	Universale
versione minima di KMDF	1.0
versione minima di UMDF	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)