WdfUsbTargetDeviceFormatRequestForString 関数 (wdfusb.h)

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

このメソッドは、他の 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;
}

要件

こちらもご覧ください

USB_CONFIGURATION_DESCRIPTOR

USB_DEVICE_DESCRIPTOR

USB_INTERFACE_DESCRIPTOR

USB_STRING_DESCRIPTOR

WDFMEMORY_OFFSET

WdfMemoryGetBuffer

WdfRequestSend

WdfRequestSetCompletionRoutine

WdfUsbTargetDeviceAllocAndQueryString

WdfUsbTargetDeviceCreateWithParameters