WdfUsbTargetDeviceAllocAndQueryString 函数 (wdfusb.h)

项目
08/08/2023

[适用于 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

USB 设备对象的句柄，该对象是从之前调用 WdfUsbTargetDeviceCreateWithParameters 获取的。

[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) ）。 (驱动程序以前将描述符存储在驱动程序定义的上下文 space 中。)

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)
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)