Metodo IWDFUsbTargetDevice::RetrieveDescriptor (wudfusb.h)

Articolo
02/07/2025

[Avviso: UMDF 2 è la versione più recente di UMDF e sostituisce UMDF 1. Tutti i nuovi driver UMDF devono essere scritti usando UMDF 2. Non vengono aggiunte nuove funzionalità a UMDF 1 ed è disponibile un supporto limitato per UMDF 1 nelle versioni più recenti di Windows 10. I driver di Windows universali devono usare UMDF 2. Per altre informazioni, vedi Introduzione a UMDF.]

Il metodo RetrieveDescriptor recupera un descrittore USB, che può descrivere un dispositivo, una configurazione o una stringa.

Sintassi

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

Parametri

[in] DescriptorType

Valore che specifica il tipo di descrittore da restituire. Questo parametro corrisponde al campo bDescriptorType di un descrittore di dispositivo standard, i cui valori sono descritti nella specifica del bus seriale universale. Questa risorsa potrebbe non essere disponibile in alcune lingue

e paesi.) Alcuni di questi valori sono elencati nella descrizione del membro DescriptorType della struttura _URB_CONTROL_DESCRIPTOR_REQUEST.

[in] Index

Indice del descrittore, in base alla specifica del bus seriale universale. Questa risorsa potrebbe non essere disponibile in alcune lingue

e paesi.)

[in] LanguageID

Identificatore della lingua, se il driver UMDF richiede un descrittore di stringa; in caso contrario, questo parametro è zero.

[in, out] BufferLength

Puntatore a una variabile che, all'input, contiene le dimensioni, in byte, del buffer a cui punta Buffer. Se l'operazione ha esito positivo, la variabile riceve il numero di byte copiati dal framework nel buffer.

[out] Buffer

Puntatore a un buffer fornito dal chiamante che riceve il descrittore USB. Il tipo di buffer deve corrispondere al valore specificato in DescriptorType.

Valore restituito

RetrieveDescriptor restituisce uno dei valori seguenti:

Codice restituito	Descrizione
S_OK	RetrieveDescriptor recuperato correttamente il descrittore USB.
E_OUTOFMEMORY	RetrieveDescriptor rilevato un errore di allocazione.
Codice di errore definito in Winerror.h	Questo valore corrisponde al codice di errore restituito dall'API WinUsb.

Osservazioni

Per informazioni sui tipi di descrittore validi che un driver UMDF può passare per il parametro DescriptorType, vedere la funzione WinUsb_GetDescriptor.

Il metodo RetrieveDescriptor genera una richiesta UMDF e invia in modo sincrono la richiesta alla destinazione di I/O.

Esempi

L'esempio di codice seguente recupera un descrittore di configurazione 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;
}

Fabbisogno

Requisito	Valore
Fine del supporto	Non disponibile in UMDF 2.0 e versioni successive.
piattaforma di destinazione	Desktop
versione minima di UMDF	1.5
intestazione	wudfusb.h (include Wudfusb.h)
dll	WUDFx.dll

Vedere anche

IWDFUsbTargetDevice

WinUsb_GetDescriptor

Condividi tramite