WdfUsbTargetDeviceRetrieveConfigDescriptor, fonction (wdfusb.h)

Article
02/07/2025

[S’applique à KMDF et UMDF]

La méthode WdfUsbTargetDeviceRetrieveConfigDescriptor récupère le descripteur de configuration USB pour le périphérique USB associé à un objet de périphérique USB de framework spécifié.

Syntaxe

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

Paramètres

[in] UsbDevice

Handle vers un objet de périphérique USB obtenu à partir d’un appel précédent à WdfUsbTargetDeviceCreateWithParameters.

[out] ConfigDescriptor

Pointeur vers une mémoire tampon allouée par l’appelant qui reçoit une structure USB_CONFIGURATION_DESCRIPTOR, suivie d’une ou plusieurs structures USB_INTERFACE_DESCRIPTOR et USB_ENDPOINT_DESCRIPTOR. Ce paramètre est facultatif et peut être NULL, auquel cas WdfUsbTargetDeviceRetrieveConfigDescriptor retourne la longueur de mémoire tampon requise. Pour plus d’informations, consultez la section Remarques suivante.

[in, out] ConfigDescriptorLength

Pointeur vers un emplacement qui fournit la longueur de la mémoire tampon vers laquelle ConfigDescriptor pointe. Si le pointeur fourni pour ConfigDescriptor est NULL, WdfUsbTargetDeviceRetrieveConfigDescriptor retourne la longueur de mémoire tampon requise à l’emplacement auquel pointe ConfigDescriptorLength.

Valeur de retour

WdfUsbTargetDeviceRetrieveConfigDescriptor retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

Retourner le code	Description
STATUS_INVALID_DEVICE_STATE	Un descripteur de configuration n’était pas disponible pour la cible spécifiée.
STATUS_INVALID_PARAMETER	Un paramètre non valide a été détecté.
STATUS_BUFFER_TOO_SMALL	La taille de mémoire tampon spécifiée était trop petite pour les données, ou l’appelant a fourni NULL pour le paramètre ConfigDescriptor.

Cette méthode peut également retourner d’autres valeurs NTSTATUS .

Une vérification de bogue se produit si le pilote fournit un handle d’objet non valide.

Remarques

La méthode WdfUsbTargetDeviceRetrieveConfigDescriptor récupère toutes les informations de configuration de l’appareil USB spécifiées (autrement dit, le descripteur de configuration ainsi que les descripteurs d’interface ou de point de terminaison susceptibles d’être présents). Pour en savoir plus sur le format de ces informations, consultez la spécification USB.

Vous pouvez utiliser WdfUsbTargetDeviceSelectConfig pour sélectionner uniquement la première configuration USB répertoriée dans la liste des descripteurs, mais vous pouvez sélectionner plusieurs interfaces dans cette configuration unique.

Les pilotes doivent appeler WdfUsbTargetDeviceRetrieveConfigDescriptor deux fois, comme suit :

Définissez le pointeur ConfigDescriptor sur NULL, afin que WdfUsbTargetDeviceRetrieveConfigDescriptor retourne la taille de mémoire tampon requise dans l’adresse vers laquelle ConfigDescriptorLeng th pointe vers.
Allouez de l’espace tampon pour contenir les informations de configuration. Par exemple, un pilote peut appeler ExAllocatePoolWithTag pour allouer une mémoire tampon, ou appeler WdfMemoryCreate pour créer un objet mémoire de framework.
Appelez WdfUsbTargetDeviceRetrieveConfigDescriptor à nouveau, en lui transmettant un pointeur vers la nouvelle mémoire tampon et la taille de la mémoire tampon.

Après le deuxième appel à WdfUsbTargetDeviceRetrieveConfigDescriptor retourne, la mémoire tampon pointée par ConfigDescriptor contient une structure USB_CONFIGURATION_DESCRIPTOR, suivie d’une ou plusieurs structures USB_INTERFACE_DESCRIPTOR et USB_ENDPOINT_DESCRIPTOR. Ces dernières structures sont organisées dans l’ordre décrit dans la spécification USB.

Pour plus d’informations sur la méthode WdfUsbTargetDeviceRetrieveConfigDescriptor et les cibles d’E/S USB, consultez cibles d’E/S USB.

Exemples

L’exemple de code suivant appelle WdfUsbTargetDeviceRetrieveConfigDescriptor pour obtenir la taille de mémoire tampon requise, appelle WdfMemoryCreate pour créer un objet mémoire et une mémoire tampon, puis appelle WdfUsbTargetDeviceRetrieveConfigDescriptor de nouveau pour obtenir les informations de configuration d’un appareil.

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;
}

Exigences

Exigence	Valeur
plateforme cible	Universel
version minimale de KMDF	1.0
version minimale de UMDF	2.0
d’en-tête	wdfusb.h (include Wdfusb.h)
bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)