Метод IWDFUsbTargetDevice::RetrieveDescriptor (wudfusb.h)

Статья
02/07/2025

[ предупреждение: UMDF 2 является последней версией UMDF и заменяет UMDF 1. Все новые драйверы UMDF должны быть написаны с помощью UMDF 2. Новые функции не добавляются в UMDF 1, а поддержка UMDF 1 в более новых версиях Windows 10 ограничена. Универсальные драйверы Windows должны использовать UMDF 2. Дополнительные сведения см. в разделе Начало работы с UMDF.]

Метод RetrieveDescriptor извлекает дескриптор USB, который может описать устройство, конфигурацию или строку.

Синтаксис

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

Параметры

[in] DescriptorType

Значение, указывающее тип возвращаемого дескриптора. Этот параметр соответствует полю bDescriptorType дескриптора стандартного устройства, значения которого описаны в спецификации универсальной последовательной шины. (Этот ресурс может быть недоступен на некоторых языках

и страны.) Некоторые из этих значений перечислены в описании элемента DescriptorType структуры _URB_CONTROL_DESCRIPTOR_REQUEST.

[in] Index

Индекс дескриптора в соответствии с спецификацией универсальной последовательной шины. (Этот ресурс может быть недоступен на некоторых языках

и страны.)

[in] LanguageID

Идентификатор языка, если драйвер UMDF запрашивает дескриптор строки; в противном случае этот параметр равен нулю.

[in, out] BufferLength

Указатель на переменную, содержащую размер в байтах буфера, на который указывает буфер буфер. Если операция выполнена успешно, переменная получает количество байтов, скопированных платформой в буфер.

[out] Buffer

Указатель на предоставленный вызывающим буфером, который получает дескриптор USB. Тип буфера должен соответствовать значению, указанному в DescriptorType.

Возвращаемое значение

RetrieveDescriptor возвращает одно из следующих значений:

Возвращаемый код	Описание
S_OK	RetrieveDescriptor успешно извлек дескриптор USB.
E_OUTOFMEMORY	RetrieveDescriptor возникла ошибка выделения.
Код ошибки, определенный в Winerror.h	Это значение соответствует коду ошибки, возвращенной API WinUsb.

Замечания

Сведения о допустимых типах дескрипторов, которые драйвер UMDF может передавать для параметра DescriptorType, см. в функции WinUsb_GetDescriptor.

Метод GetDescriptor создает запрос UMDF и синхронно отправляет запрос в целевой объект ввода-вывода.

Примеры

В следующем примере кода извлекается дескриптор конфигурации 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;
}

Требования

Требование	Ценность
завершение поддержки	Недоступно в UMDF 2.0 и более поздних версиях.
целевая платформа	Настольный
минимальная версия UMDF	1.5
заголовка	wudfusb.h (include Wudfusb.h)
DLL	WUDFx.dll

См. также

IWDFUsbTargetDevice

WinUsb_GetDescriptor

Поделиться через