WdfUsbTargetDeviceAllocAndQueryString 函数（wdfusb.h）

2025-02-07

[适用于 KMDF 和 UMDF]

WdfUsbTargetDeviceAllocAndQueryString 方法分配缓冲区，然后检索与指定的 USB 设备和描述符索引值关联的 Unicode 字符串。

语法

NTSTATUS WdfUsbTargetDeviceAllocAndQueryString(
  [in]            WDFUSBDEVICE           UsbDevice,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES StringMemoryAttributes,
  [out]           WDFMEMORY              *StringMemory,
  [out, optional] PUSHORT                NumCharacters,
  [in]            UCHAR                  StringIndex,
  [in, optional]  USHORT                 LangID
);

参数

[in] UsbDevice

从上一次调用 WdfUsbTargetDeviceCreateWithParameters获取的 USB 设备对象的句柄。

[in, optional] StringMemoryAttributes

指向调用方分配 WDF_OBJECT_ATTRIBUTES 结构的指针，该结构包含新内存对象的调用方提供的属性。此参数是可选的，可以WDF_NO_OBJECT_ATTRIBUTES。

[out] StringMemory

指向接收包含 Unicode 字符串的内存对象的句柄的位置的指针。仅当设备提供以 NULL 结尾的字符串时，该字符串才以 NULL 结尾。

[out, optional] NumCharacters

指向接收字符串描述符中包含的字符数的位置的指针。如果 Unicode 字符串以 NULL 结尾，则此数字包括 NULL 字符。此参数是可选的，可以 NULL。

[in] StringIndex

标识 Unicode 字符串的索引值。此索引值是从 USB_DEVICE_DESCRIPTOR、USB_CONFIGURATION_DESCRIPTOR或 USB_INTERFACE_DESCRIPTOR 结构获取的。

[in, optional] LangID

语言标识符。将为此标识符指定的语言检索 Unicode 字符串。有关获取设备支持的语言标识符的信息，请参阅 USB 规范。

返回值

WdfUsbTargetDeviceAllocAndQueryString 如果作成功，则返回STATUS_SUCCESS。否则，此方法可以返回以下值之一：

返回代码	描述
STATUS_INVALID_PARAMETER	检测到无效参数。
STATUS_INSUFFICIENT_RESOURCES	无法分配内存缓冲区。
STATUS_DEVICE_DATA_ERROR	USB 设备返回了无效的描述符。
STATUS_BUFFER_OVERFLOW	提供的缓冲区太小。

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

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

言论

WdfUsbTargetDeviceAllocAndQueryString 方法（驱动程序只需调用一次以获取字符串描述符）是 WdfUsbTargetDeviceQueryString 方法的替代方法，该方法必须调用两次才能获取字符串。

该方法查找指定的 USB 字符串描述符，将描述符中的 Unicode 字符串复制到内存对象，并将句柄返回到内存对象。

调用 WdfUsbTargetDeviceAllocAndQueryString后，驱动程序可以将 StringMemory 句柄传递给 WdfMemoryGetBuffer 以访问内存对象的内容。

有关 USB 字符串描述符的详细信息，请参阅 USB 规范。

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

例子

下面的代码示例调用 WdfUsbTargetDeviceAllocAndQueryString，从 USB 设备描述符获取制造商的名称字符串（以美国英语（0x0409）。（驱动程序以前将描述符存储在驱动程序定义的上下文空间中。

PMY_DEVICE_CONTEXT  myDeviceContext;
WDFMEMORY  memoryHandle;
USHORT  numCharacters;

myDeviceContext = GetDeviceContext(device);

status = WdfUsbTargetDeviceAllocAndQueryString(
                                        myDeviceContext->UsbTargetDevice,
                                        WDF_NO_OBJECT_ATTRIBUTES,
                                        &memoryHandle,
                                        &numCharacters,
                                        myDeviceContext->UsbDeviceDescr.iManufacturer,
                                        0x0409
                                        );

要求

要求	价值
目标平台	普遍
最低 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）