Функция WdfUsbTargetDeviceRetrieveConfigDescriptor (wdfusb.h)

Статья
02/07/2025

[Применимо к KMDF и UMDF]

Метод WdfUsbTargetDeviceRetrieveConfigDescriptor извлекает дескриптор конфигурации USB для USB-устройства, связанного с указанным объектом USB-устройства платформы.

Синтаксис

NTSTATUS WdfUsbTargetDeviceRetrieveConfigDescriptor(
  [in]      WDFUSBDEVICE UsbDevice,
  [out]     PVOID        ConfigDescriptor,
  [in, out] PUSHORT      ConfigDescriptorLength
);

Параметры

[in] UsbDevice

Дескриптор объекта USB-устройства, полученный из предыдущего вызова WdfUsbTargetDeviceCreateWithParameters.

[out] ConfigDescriptor

Указатель на выделенный вызывающим буфером, который получает USB_CONFIGURATION_DESCRIPTOR структуру, за которой следует одна или несколько USB_INTERFACE_DESCRIPTOR и USB_ENDPOINT_DESCRIPTOR структур. Этот параметр является необязательным и может быть null, в этом случае WdfUsbTargetDeviceRetrieveConfigDescriptor возвращает необходимую длину буфера. Дополнительные сведения см. в следующем разделе "Примечания".

[in, out] ConfigDescriptorLength

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

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

WdfUsbTargetDeviceRetrieveConfigDescriptor возвращает STATUS_SUCCESS, если операция завершится успешно. В противном случае этот метод может вернуть одно из следующих значений:

Возвращаемый код	Описание
STATUS_INVALID_DEVICE_STATE	Дескриптор конфигурации недоступен для указанного целевого объекта.
STATUS_INVALID_PARAMETER	Обнаружен недопустимый параметр.
STATUS_BUFFER_TOO_SMALL	Указанный размер буфера слишком мал для данных или вызывающий объект, предоставленный NULL для параметра ConfigDescriptor.

Этот метод также может возвращать другие значения NTSTATUS.

Ошибка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Замечания

Метод WdfUsbTargetDeviceRetrieveConfigDescriptor извлекает все сведения о конфигурации указанного USB-устройства (то есть дескриптор конфигурации, а также все дескрипторы интерфейса или дескрипторы конечной точки, которые могут присутствовать). Сведения о формате этой информации см. в спецификации USB.

Вы можете использовать WdfUsbTargetDeviceSelectConfig, чтобы выбрать только первую конфигурацию USB, указанную в списке дескрипторов, но в рамках этой одной конфигурации можно выбрать несколько интерфейсов.

Драйверы должны вызывать WdfUsbTargetDeviceRetrieveConfigDescriptor дважды, как показано ниже.

Задайте указатель ConfigDescriptor на NULL, чтобы WdfUsbTargetDeviceRetrieveConfigDescriptor вернет требуемый размер буфера в адресе, на который ConfigDescriptorLength.
Выделите буферное пространство для хранения сведений о конфигурации. Например, драйвер может вызвать ExAllocatePoolWithTag для выделения буфера или вызвать WdfMemoryCreate для создания объекта памяти платформы.
Вызовите WdfUsbTargetDeviceRetrieveConfigDescriptor еще раз, передав указатель на новый буфер и размер буфера.

После второго вызова WdfUsbTargetDeviceRetrieveConfigDescriptor возвращается буфер, указывающий на ConfigDescriptor содержит структуру USB_CONFIGURATION_DESCRIPTOR, за которой следует одна или несколько USB_INTERFACE_DESCRIPTOR и USB_ENDPOINT_DESCRIPTOR структур. Эти последние структуры упорядочены в порядке, описанном в спецификации USB.

Дополнительные сведения о методе WdfUsbTargetDeviceRetrieveConfigDescriptor и целевых объектов USB-ввода-вывода см. в целевых объектов USB-ввода-вывода.

Примеры

Следующий пример кода вызывает WdfUsbTargetDeviceRetrieveConfigDescriptor для получения требуемого размера буфера, вызовов WdfMemoryCreate для создания объекта памяти и буфера, а затем вызывает WdfUsbTargetDeviceRetrieveConfigDescriptor, чтобы получить сведения о конфигурации устройства.

USHORT  size;
NTSTATUS  ntStatus;
PMY_DEVICE_CONTEXT  myDeviceContext;
PUSB_CONFIGURATION_DESCRIPTOR  configurationDescriptor = NULL;
WDF_OBJECT_ATTRIBUTES  objectAttribs;
WDFMEMORY  memoryHandle;

myDeviceContext = GetDeviceContext(Device);

ntStatus = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                            myDeviceContext->WdfUsbTargetDevice,
                                            NULL,
                                            &size
                                            );

if (ntStatus != STATUS_BUFFER_TOO_SMALL) {
    return ntStatus;
}

WDF_OBJECT_ATTRIBUTES_INIT(&objectAttribs);
objectAttribs.ParentObject = myDeviceContext->WdfUsbTargetDevice;

ntStatus = WdfMemoryCreate(
                           &objectAttribs,
                           NonPagedPool,
                           POOL_TAG,
                           size,
                           &memoryHandle,
                           (PVOID)&configurationDescriptor
                           );
if (!NT_SUCCESS(ntStatus)) {
    return ntStatus;
}

ntStatus = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                            myDeviceContext->WdfUsbTargetDevice,
                                            configurationDescriptor,
                                            &size
                                            );
if (!NT_SUCCESS(ntStatus)) {
    return ntStatus;
}

Требования

Требование	Ценность
целевая платформа	Всеобщий
минимальная версия KMDF	1.0
минимальная версия UMDF	2.0
заголовка	wdfusb.h (include Wdfusb.h)
библиотеки	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
правил соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)