WdfUsbTargetDeviceFormatRequestForString 関数 (wdfusb.h)

[アーティクル]
08/08/2023

[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を返します。それ以外の場合、このメソッドは次のいずれかの値を返すことができます。

リターンコード	説明
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;
}

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
最小 UMDF バージョン	2.0
Header	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)、 RequestSendAndForgetNoFormatting2(kmdf)、 UsbKmdfIrql(kmdf)、 UsbKmdfIrql2(kmdf)、UsbKmdfIrqlExplicit(kmdf)