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

Artigo
02/07/2025

[Aviso: UMDF 2 é a versão mais recente do UMDF e substitui o UMDF 1. Todos os novos drivers UMDF devem ser gravados usando UMDF 2. Nenhum recurso novo está sendo adicionado ao UMDF 1 e há suporte limitado para UMDF 1 em versões mais recentes do Windows 10. Os drivers universais do Windows devem usar o UMDF 2. Para obter mais informações, consulte Introdução aoda UMDF .]

O método RetrieveDescriptor recupera um descritor USB, que pode descrever um dispositivo, configuração ou cadeia de caracteres.

Sintaxe

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

Parâmetros

[in] DescriptorType

Um valor que especifica o tipo de descritor a ser retornado. Esse parâmetro corresponde ao campo bDescriptorType de um descritor de dispositivo padrão, cujos valores são descritos na especificação do Barramento Serial Universal. (Esse recurso pode não estar disponível em alguns idiomas

e países.) Alguns desses valores são listados na descrição do membro DescriptorType da estrutura _URB_CONTROL_DESCRIPTOR_REQUEST.

[in] Index

O índice do descritor, de acordo com a especificação do Barramento Serial Universal. (Esse recurso pode não estar disponível em alguns idiomas

e países.)

[in] LanguageID

O identificador do idioma, se o driver UMDF solicitar um descritor de cadeia de caracteres; caso contrário, esse parâmetro é zero.

[in, out] BufferLength

Um ponteiro para uma variável que, na entrada, contém o tamanho, em bytes, do buffer ao qual o buffer aponta. Se a operação for bem-sucedida, a variável receberá o número de bytes que a estrutura copiou para o buffer.

[out] Buffer

Um ponteiro para um buffer fornecido pelo chamador que recebe o descritor USB. O tipo de buffer deve corresponder ao valor especificado em DescriptorType.

Valor de retorno

RetrieveDescriptor retorna um dos seguintes valores:

Código de retorno	Descrição
S_OK	RetrieveDescriptor recuperou com êxito o descritor USB.
E_OUTOFMEMORY	RetrieveDescriptor encontrou uma falha de alocação.
Um código de erro definido em Winerror.h	Esse valor corresponde ao código de erro retornado pela API do WinUsb.

Observações

Para obter informações sobre tipos de descritor válidos que um driver UMDF pode passar para o parâmetro DescriptorType, consulte a função WinUsb_GetDescriptor.

O método RetrieveDescriptor gera uma solicitação UMDF e envia a solicitação de forma síncrona para o destino de E/S.

Exemplos

O exemplo de código a seguir recupera um descritor de configuração 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;
}

Requisitos

Requisito	Valor
fim do suporte	Indisponível no UMDF 2.0 e posterior.
da Plataforma de Destino	Área de trabalho
versão mínima do UMDF	1.5
cabeçalho	wudfusb.h (inclua Wudfusb.h)
de DLL	WUDFx.dll

Consulte também

IWDFUsbTargetDevice

WinUsb_GetDescriptor

Compartilhar via