WdfUsbTargetDeviceAllocAndQueryString 函数 (wdfusb.h)

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

另请参阅

USB_CONFIGURATION_DESCRIPTOR

USB_DEVICE_DESCRIPTOR

USB_INTERFACE_DESCRIPTOR

WDF_OBJECT_ATTRIBUTES

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceQueryString