IWDFUsbTargetDevice ::RetrieveDescriptor, méthode (wudfusb.h)

Article
02/07/2025

[Avertissement : UMDF 2 est la dernière version de UMDF et remplace UMDF 1. Tous les nouveaux pilotes UMDF doivent être écrits à l’aide de UMDF 2. Aucune nouvelle fonctionnalité n’est ajoutée à UMDF 1 et il existe une prise en charge limitée de UMDF 1 sur les versions plus récentes de Windows 10. Les pilotes Windows universels doivent utiliser UMDF 2. Pour plus d’informations, consultez Bien démarrer avec UMDF.]

La méthode RetrieveDescriptor récupère un descripteur USB, qui peut décrire un appareil, une configuration ou une chaîne.

Syntaxe

HRESULT RetrieveDescriptor(
  [in]      UCHAR  DescriptorType,
  [in]      UCHAR  Index,
  [in]      USHORT LanguageID,
  [in, out] ULONG  *BufferLength,
  [out]     PVOID  Buffer
);

Paramètres

[in] DescriptorType

Valeur qui spécifie le type de descripteur à retourner. Ce paramètre correspond au champ bDescriptorType d’un descripteur d’appareil standard, dont les valeurs sont décrites dans la spécification Universal Serial Bus. (Cette ressource peut ne pas être disponible dans certaines langues

et pays.) Certaines de ces valeurs sont répertoriées dans la description du membre DescriptorType de la structure _URB_CONTROL_DESCRIPTOR_REQUEST.

[in] Index

Index du descripteur, conformément à la spécification de bus série universel. (Cette ressource peut ne pas être disponible dans certaines langues

et pays.)

[in] LanguageID

Identificateur du langage, si le pilote UMDF demande un descripteur de chaîne ; sinon, ce paramètre est égal à zéro.

[in, out] BufferLength

Pointeur vers une variable qui, en entrée, contient la taille, en octets, de la mémoire tampon vers laquelle pointe la mémoire tampon tampon. Si l’opération réussit, la variable reçoit le nombre d’octets que l’infrastructure a copiés dans la mémoire tampon.

[out] Buffer

Pointeur vers une mémoire tampon fournie par l’appelant qui reçoit le descripteur USB. Le type de mémoire tampon doit correspondre à la valeur spécifiée dans DescriptorType.

Valeur de retour

RetrieveDescriptor retourne l’une des valeurs suivantes :

Retourner le code	Description
S_OK	RetrieveDescriptor récupéré avec succès le descripteur USB.
E_OUTOFMEMORY	RetrieveDescriptor a rencontré un échec d’allocation.
Code d’erreur défini dans Winerror.h	Cette valeur correspond au code d’erreur retourné par l’API WinUsb.

Remarques

Pour plus d’informations sur les types de descripteurs valides qu’un pilote UMDF peut passer pour le paramètre DescriptorType, consultez la fonction WinUsb_GetDescriptor.

La méthode RetrieveDescriptor génère une requête UMDF et envoie de façon synchrone la requête à la cible d’E/S.

Exemples

L’exemple de code suivant récupère un descripteur de configuration USB.

HRESULT
CUmdfHidDevice::RetrieveConfigDescriptor(
    __out_bcount(ConfigDescriptorCb) PUSB_CONFIGURATION_DESCRIPTOR *ConfigDescriptor,
    __out ULONG *ConfigDescriptorCb
    )
{
    ULONG descriptorCb = sizeof(USB_CONFIGURATION_DESCRIPTOR);
    USB_CONFIGURATION_DESCRIPTOR descriptorHeader;
    PBYTE descriptorBuffer;
    HRESULT hr;

    //
    // Get the configuration descriptor at index 0
    //

    hr = m_UsbTargetDevice->RetrieveDescriptor(
                            USB_CONFIGURATION_DESCRIPTOR_TYPE,
                            0,
                            0,
                            &descriptorCb,
                            &descriptorHeader
                            );
    //
    // Store the buffer in the output parameter, or delete it.
    //
    if (SUCCEEDED(hr)) {
        *ConfigDescriptor = (PUSB_CONFIGURATION_DESCRIPTOR) (descriptorHeader);
        *ConfigDescriptorCb = descriptorCb;
    }
    else {
        delete[] descriptorHeader;
    }
    return hr;
}

Exigences

Exigence	Valeur
fin du support	Indisponible dans UMDF 2.0 et versions ultérieures.
plateforme cible	Bureau
version minimale de UMDF	1.5
d’en-tête	wudfusb.h (include Wudfusb.h)
DLL	WUDFx.dll

Voir aussi

IWDFUsbTargetDevice

WinUsb_GetDescriptor

Partager via