WdfUsbTargetDeviceRetrieveConfigDescriptor 函数 (wdfusb.h)

[适用于 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。 否则，此方法可以返回以下值之一：

此方法还可能返回其他 NTSTATUS 值。

如果驱动程序提供无效的对象句柄，则会发生 bug 检查。

注解

WdfUsbTargetDeviceRetrieveConfigDescriptor 方法检索指定 USB 设备的所有配置信息 (即配置描述符以及可能) 存在的任何接口或终结点描述符。 若要了解此信息的格式，请参阅 USB 规范。

可以使用 WdfUsbTargetDeviceSelectConfig 仅选择描述符列表中列出的第一个 USB 配置，但可以在此单个配置中选择多个接口。

驱动程序应调用 WdfUsbTargetDeviceRetrieveConfigDescriptor 两次，如下所示：

1. 将 ConfigDescriptor 指针设置为 NULL，以便 WdfUsbTargetDeviceRetrieveConfigDescriptor 将在 ConfigDescriptorLength 指向的地址中返回所需的缓冲区大小。
2. 分配缓冲区空间以保存配置信息。 例如，驱动程序可以调用 ExAllocatePoolWithTag 来分配缓冲区，也可以调用 WdfMemoryCreate 来创建框架内存对象。
3. 再次调用 WdfUsbTargetDeviceRetrieveConfigDescriptor ，向其传递指向新缓冲区和缓冲区大小的指针。

有关 WdfUsbTargetDeviceRetrieveConfigDescriptor 方法和 USB I/O 目标的详细信息，请参阅 USB I/O 目标。

示例

下面的代码示例调用 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;
}

要求

另请参阅

ExAllocatePoolWithTag

USB_CONFIGURATION_DESCRIPTOR

USB_ENDPOINT_DESCRIPTOR

USB_INTERFACE_DESCRIPTOR

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceGetDeviceDescriptor