WdfUsbTargetDeviceQueryString 函数（wdfusb.h）

项目
07/16/2024

[适用于 KMDF 和 UMDF]

WdfUsbTargetDeviceQueryString 方法检索与指定 USB 设备和描述符索引值关联的 Unicode 字符串。

语法

NTSTATUS WdfUsbTargetDeviceQueryString(
  [in]            WDFUSBDEVICE              UsbDevice,
  [in, optional]  WDFREQUEST                Request,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [out, optional] PUSHORT                   String,
  [in, out]       PUSHORT                   NumCharacters,
  [in]            UCHAR                     StringIndex,
  [in, optional]  USHORT                    LangID
);

参数

[in] UsbDevice

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

[in, optional] Request

框架请求对象的句柄。此参数是可选的，可以 NULL。有关详细信息，请参阅以下“备注”部分。

[in, optional] RequestOptions

指向调用方分配 WDF_REQUEST_SEND_OPTIONS 结构的指针，该结构指定请求的选项。此指针是可选的，可以 NULL。有关详细信息，请参阅以下“备注”部分。

[out, optional] String

指向调用方分配的缓冲区的指针，该缓冲区接收请求的 Unicode 字符串。仅当设备提供以 NULL 结尾的字符串时，该字符串才以 NULL 结尾。如果此指针 NULL，WdfUsbTargetDeviceQueryString 返回 NumCharacters 指向的位置所需的缓冲区大小（即所需的 Unicode 字符数）。

[in, out] NumCharacters

指向调用方分配的变量的指针。调用方提供缓冲区可以容纳的 Unicode 字符数。当 WdfUsbTargetDeviceQueryString 返回时，变量将接收 字符串 缓冲区接收的 Unicode 字符串中的字符数（包括 NULL 终止符（如果提供）。

[in] StringIndex

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

[in, optional] LangID

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

返回值

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

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

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

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

言论

驱动程序应使用以下步骤调用 WdfUsbTargetDeviceQueryString 两次：

将 字符串 指针设置为 NULL，以便 WdfUsbTargetDeviceQueryString 将返回 NumCharacters 参数指向的地址中所需的缓冲区大小。
分配缓冲区空间以保存请求字符串中的 Unicode 字符数。例如，驱动程序可以调用 ExAllocatePoolWithTag 来分配缓冲区，或者它可以调用 WdfMemoryCreate 来创建框架内存对象。
再次调用 WdfUsbTargetDeviceQueryString，将 String 值设置为指向新缓冲区的指针，并将 NumCharacters 到缓冲区的长度（即 Unicode 字符数，而不是字节长度）。

WdfUsbTargetDeviceQueryString 找到指定的 USB 字符串描述符，并将 Unicode 字符串从描述符复制到提供的缓冲区中。

如果驱动程序为 Request 参数指定了非NULL 值，则框架将使用指定的请求对象，并且另一个驱动程序线程可以根据需要调用 WdfRequestCancelSentRequest，以尝试取消字符串查询请求。如果驱动程序为请求指定 NULL 值，则框架将使用驱动程序无法取消的内部请求对象。

驱动程序可以指定非NULLRequestOptions 参数，无论驱动程序提供非NULL 还是 NULLRequest 参数。例如，可以使用 RequestOptions 参数指定超时值。

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

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

例子

下面的代码示例调用 WdfUsbTargetDeviceQueryString 以获取所需的缓冲区大小，调用 WdfMemoryCreate 创建内存对象和缓冲区，然后再次调用 WdfUsbTargetDeviceQueryString，以获取来自 USB 设备描述符的制造商名称字符串（0x0409）。（驱动程序以前将描述符存储在驱动程序定义的上下文空间中。

PMY_DEVICE_CONTEXT  myDeviceContext;
USHORT  numCharacters;
PUSHORT  stringBuf;
WDFMEMORY  memoryHandle;

myDeviceContext = GetDeviceContext(device);

status = WdfUsbTargetDeviceQueryString(
                                       myDeviceContext->UsbTargetDevice,
                                       NULL,
                                       NULL,
                                       NULL,
                                       &numCharacters,
                                       myDeviceContext->UsbDeviceDescr.iManufacturer,
                                       0x0409
                                       );

ntStatus = WdfMemoryCreate(
                           WDF_NO_OBJECT_ATTRIBUTES,
                           NonPagedPool,
                           POOL_TAG,
                           numCharacters * sizeof(WCHAR),
                           &memoryHandle,
                           (PVOID)&stringBuf
                           );
if (!NT_SUCCESS(ntStatus)) {
    return ntStatus;
}
status = WdfUsbTargetDeviceQueryString(
                                       myDeviceContext->UsbTargetDevice,
                                       NULL,
                                       NULL,
                                       stringBuf,
                                       &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）