WdfUsbTargetDeviceFormatRequestForString 函数 (wdfusb.h)

项目
02/27/2024

[适用于 KMDF 和 UMDF]

WdfUsbTargetDeviceFormatRequestForString 方法生成与 USB 设备的字符串索引值关联的 USB 字符串描述符的请求。

语法

NTSTATUS WdfUsbTargetDeviceFormatRequestForString(
  [in]           WDFUSBDEVICE      UsbDevice,
  [in]           WDFREQUEST        Request,
  [in]           WDFMEMORY         Memory,
  [in, optional] PWDFMEMORY_OFFSET Offset,
  [in]           UCHAR             StringIndex,
  [in, optional] USHORT            LangID
);

参数

[in] UsbDevice

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

[in] Request

框架请求对象的句柄。

[in] Memory

框架内存对象的句柄。

[in, optional] Offset

指向调用方分配的WDFMEMORY_OFFSET 结构的指针，该结构提供可选的字节偏移量和长度值。框架使用这些值来确定输出缓冲区中用于存储字符串描述符的起始地址和长度。如果此指针为 NULL，则描述符存储在输出缓冲区的开头，最大字符串长度为缓冲区长度。

[in] StringIndex

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

[in, optional] LangID

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

返回值

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

返回代码	说明
STATUS_INVALID_PARAMETER	缓冲区的字节计数不是偶数。
STATUS_INSUFFICIENT_RESOURCES	内存不足。
STATUS_INTEGER_OVERFLOW	Offset 指定的偏移量无效。

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

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

注解

WdfUsbTargetDeviceFormatRequestForString 返回后，驱动程序必须调用 WdfRequestSend 以发送请求。 WdfRequestSend 返回后，驱动程序可以将内存句柄传递给 WdfMemoryGetBuffer 以获取指向内存缓冲区的指针。缓冲区将包含描述字符串描述符的USB_STRING_DESCRIPTOR 结构。

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

示例

下面的代码示例创建一个请求对象和一个内存对象，并将对象句柄传递给 WdfUsbTargetDeviceFormatRequestForString。然后，该示例为请求设置 CompletionRoutine 回调函数，并将请求发送到 I/O 目标。

NTSTATUS status;
PDEVICE_CONTEXT deviceContext = GetDeviceContext(device);
WDFREQUEST request;
WDFMEMORY memHandle;
WDF_OBJECT_ATTRIBUTES attributes;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);

status = WdfRequestCreate(
    &attributes,
    WdfUsbTargetDeviceGetIoTarget(deviceContext->UsbTargetDevice),
    &request);

if (!NT_SUCCESS(status)) {
    return status;
}

status = WdfMemoryCreate(
    WDF_NO_OBJECT_ATTRIBUTES,
    NonPagedPool,
    0,
    STR_DESC_STRING_SIZE,
    &memHandle,
    NULL);
if (!NT_SUCCESS(status)) {
    WdfObjectDelete(request);
    return status;
}

status = WdfUsbTargetDeviceFormatRequestForString(
    deviceContext->UsbTargetDevice,
    request,
    memHandle,
    NULL,
    deviceContext->UsbDeviceDescr.iManufacturer,
    0x0409);

if (NT_SUCCESS(status)) {
    WdfRequestSetCompletionRoutine(
        request,
        MyCompletionRoutine,
        NULL);

    if (WdfRequestSend(
            request,
            WdfUsbTargetDeviceGetIoTarget(deviceContext->UsbTargetDevice),
            NULL)) {
        status = STATUS_PENDING;
    }
    
}
else {
    WdfObjectDelete(memHandle);
    WdfObjectDelete(request);
    return status;
}

要求

要求	值
目标平台	通用
最低 KMDF 版本	1.0
最低 UMDF 版本	2.0
标头	wdfusb.h (包括 Wdfusb.h)
Library	Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI 符合性规则	DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf) ， RequestFormattedValid (kmdf) 、 RequestForUrbXrb (kmdf) 、 RequestSendAndForgetNoFormatting (kmdf) 、 RequestSendAndForgetNoFormatting 2 (kmdf) 、 UsbKmdfIrql (kmdf) 、 UsbKmdfIrql2 (kmdf) 、UsbKmdfIrqlExplicit (kmdf)