WdfUsbTargetDeviceQueryString 函数 (wdfusb.h)

项目
02/27/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

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

[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 返回时，变量接收字符数 (包括 NULL 终止符（如果提供) 字符串缓冲区接收的 Unicode 字符串中）。

[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 两次：

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

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

如果驱动程序为 Request 参数指定了非 NULL 值，框架将使用指定的请求对象，并且另一个驱动程序线程可以调用 WdfRequestCancelSentRequest（如有必要），以尝试取消字符串查询请求。如果驱动程序为 Request 指定 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)
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)