Metodo IWDFUsbTargetDevice::RetrieveDescriptor (wudfusb.h)

Articolo
02/27/2024

[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 info, vedi Introduzione con 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 universal serial bus . 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 a cui, all'input, sono contenute 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 ha recuperato correttamente il descrittore USB.
E_OUTOFMEMORY	RetrieveDescriptor ha rilevato un errore di allocazione.
Codice di errore definito in Winerror.h	Questo valore corrisponde al codice di errore restituito dall'API WinUsb.

Commenti

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.

Esempio

Nell'esempio di codice seguente viene recuperato 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;
}

Requisiti

Requisito	Valore
Fine del supporto	Non disponibile in UMDF 2.0 e versioni successive.
Piattaforma di destinazione	Desktop
Versione UMDF minima	1.5
Intestazione	wudfusb.h (include Wudfusb.h)
DLL	WUDFx.dll

Vedi anche

IWDFUsbTargetDevice

WinUsb_GetDescriptor

Condividi tramite