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

Статья
08/08/2023

[Относится к 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 (включая 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)