Méthode IWDFUsbTargetDevice ::RetrieveDescriptor (wudfusb.h)

Article
02/27/2024

[Avertissement : UMDF 2 est la dernière version d’UMDF et remplace UMDF 1. Tous les nouveaux pilotes UMDF doivent être écrits à l’aide d’UMDF 2. Aucune nouvelle fonctionnalité n’est ajoutée à UMDF 1 et la prise en charge d’UMDF 1 est limitée sur les versions plus récentes de Windows 10. Les pilotes Windows universels doivent utiliser UMDF 2. Pour plus d’informations, consultez Prise en main 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, selon la spécification Universal Serial Bus . (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 la mémoire tampon pointe. 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 retournée

RetrieveDescriptor retourne l’une des valeurs suivantes :

Code de retour	Description
S_OK	RetrieveDescriptor a correctement récupéré 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 demande à 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;
}

Configuration requise

Condition requise	Valeur
Fin de la prise en charge	Non disponible dans UMDF 2.0 et versions ultérieures.
Plateforme cible	Desktop (Expérience utilisateur)
Version UMDF minimale	1.5
En-tête	wudfusb.h (inclure Wudfusb.h)
DLL	WUDFx.dll

Voir aussi

IWDFUsbTargetDevice

WinUsb_GetDescriptor

Partager via