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を返します。 それ以外の場合、このメソッドは次のいずれかの値を返すことができます。
リターン コード | 説明 |
---|---|
|
バッファーのバイト数が偶数ではありません。 |
|
メモリが不足していました。 |
|
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) |
こちらもご覧ください
WdfRequestSetCompletionRoutine