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

從先前呼叫 WdfUsbTargetDeviceCreateWithParameters 取得的 USB 裝置物件的句柄。

[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。否則，這個方法可以傳回下列其中一個值：

傳回碼	Description
STATUS_INVALID_PARAMETER	緩衝區的位元組計數不是偶數。
STATUS_INSUFFICIENT_RESOURCES	記憶體不足。
STATUS_INTEGER_OVERFLOW	Offset 指定的位移無效。

這個方法也可能傳回其他 NTSTATUS值。

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

備註

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;
}

規格需求

需求	值
目標平台	Universal
最低 KMDF 版本	1.0
最低UMDF版本	2.0
標頭	wdfusb.h (包含 Wdfusb.h)
程式庫	Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI 合規性規則	DriverCreate (kmdf) ， KmdfIrql (kmdf) ， KmdfIrql2 (kmdf) ， KmdfIrqlExplicit (kmdf) ， RequestFormattedValid (kmdf) 、 RequestForUrbXrb (kmdf) 、 RequestSendAndForgetNoFormatting (kmdf) 、 RequestSendAndForgetNoFormatting2 (kmdf) 、 UsbKmdfIrql (kmdf) 、 UsbKmdfIrql2 (kmdf) 、UsbKmdfIrqlExplicit (kmdf)