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	指定的缓冲区大小对于数据来说太小，或者调用方为 ConfigDescriptor 参数提供了 NULL。

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

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

注解

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 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;
}

要求

要求	值
目标平台	通用
最低 KMDF 版本	1.0
最低 UMDF 版本	2.0
标头	wdfusb.h (包括 Wdfusb.h)
Library	Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI 符合性规则	DriverCreate (kmdf) ， KmdfIrql (kmdf) ， KmdfIrql2 (kmdf) ， KmdfIrqlExplicit (kmdf) ， UsbKmdfIrql (kmdf) 、 UsbKmdfIrql2 (kmdf) 、UsbKmdfIrqlExplicit (kmdf)