WdfUsbTargetDeviceQueryString 関数 (wdfusb.h)

[アーティクル]
07/16/2024

[KMDF と UMDF に適用]

WdfUsbTargetDeviceQueryString メソッドは、指定された USB デバイスと記述子インデックス値に関連付けられている Unicode 文字列を取得します。

構文

NTSTATUS WdfUsbTargetDeviceQueryString(
  [in]            WDFUSBDEVICE              UsbDevice,
  [in, optional]  WDFREQUEST                Request,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [out, optional] PUSHORT                   String,
  [in, out]       PUSHORT                   NumCharacters,
  [in]            UCHAR                     StringIndex,
  [in, optional]  USHORT                    LangID
);

パラメーター

[in] UsbDevice

WdfUsbTargetDeviceCreateWithParametersへの以前の呼び出しから取得された USB デバイスオブジェクトへのハンドル。

[in, optional] Request

フレームワーク要求オブジェクトへのハンドル。このパラメーターは省略可能であり、NULLできます。詳細については、次の「解説」セクションを参照してください。

[in, optional] RequestOptions

要求のオプションを指定する呼び出し元によって割り当てられた WDF_REQUEST_SEND_OPTIONS 構造体へのポインター。このポインターは省略可能であり、NULLできます。詳細については、次の「解説」セクションを参照してください。

[out, optional] String

要求された Unicode 文字列を受け取る呼び出し元によって割り当てられたバッファーへのポインター。この文字列は、デバイスが NULL で終わる文字列を提供する場合にのみ NULL で終了します。このポインターが NULL場合、WdfUsbTargetDeviceQueryString は、NumCharacters が指す位置に必要なバッファーサイズ (つまり、Unicode 文字の必要な数) 返します。

[in, out] NumCharacters

呼び出し元によって割り当てられた変数へのポインター。呼び出し元は、バッファーが保持できる Unicode 文字の数を指定します。 WdfUsbTargetDeviceQueryString が返されると、変数は、文字列 バッファーが受け取る Unicode 文字列内にある文字数 (NULL ターミネータを含む) を受け取ります。

[in] StringIndex

Unicode 文字列を識別するインデックス値。このインデックス値は、USB_DEVICE_DESCRIPTOR、USB_CONFIGURATION_DESCRIPTOR、または USB_INTERFACE_DESCRIPTOR 構造体から取得されます。

[in, optional] LangID

言語識別子。この識別子が指定する言語の Unicode 文字列が取得されます。デバイスでサポートされている言語識別子の取得については、USB 仕様を参照してください。

戻り値

WdfUsbTargetDeviceQueryString は、操作が成功した場合にSTATUS_SUCCESSを返します。それ以外の場合、このメソッドは次のいずれかの値を返すことができます。

リターンコード	形容
STATUS_INVALID_PARAMETER	無効なパラメーターが検出されました。
STATUS_INSUFFICIENT_RESOURCES	メモリバッファーを割り当てませんでした。
STATUS_DEVICE_DATA_ERROR	USB デバイスから無効な記述子が返されました。
STATUS_BUFFER_OVERFLOW	指定されたバッファーが小さすぎました。

このメソッドは、他の NTSTATUS 値を返す場合もあります。

ドライバーが無効なオブジェクトハンドルを提供すると、バグチェックが発生します。

備考

ドライバーは、次の手順 使用して、WdfUsbTargetDeviceQueryString を 2 回呼び出す必要があります。

文字列 ポインター NULLに設定して、WdfUsbTargetDeviceQueryString が、NumCharacters パラメーターが指すアドレスに必要なバッファーサイズを返すようにします。
要求された文字列内の Unicode 文字の数を保持するバッファー領域を割り当てます。たとえば、ドライバーは ExAllocatePoolWithTag 呼び出してバッファーを割り当てたり、WdfMemoryCreate 呼び出してフレームワークメモリオブジェクトを作成したりする場合があります。
WdfUsbTargetDeviceQueryString を再度呼び出し、文字列 値を新しいバッファーへのポインターに設定し、NumCharacters バッファーの長さ (つまり、バイト長ではなく Unicode 文字の数) に を設定します。

WdfUsbTargetDeviceQueryString 指定された USB 文字列記述子を検索し、指定されたバッファーに記述子から Unicode 文字列をコピーします。

ドライバーが Request パラメーターに対して非NULL 値を指定した場合、フレームワークは指定された要求オブジェクトを使用し、別のドライバースレッドは、必要に応じて、WdfRequestCancelSentRequestを呼び出して、文字列クエリ要求のキャンセルを試みることができます。ドライバーが要求の NULL 値を指定する場合、フレームワークは、ドライバーが取り消すことができない内部要求オブジェクトを使用します。

ドライバーは、以外の NULL または NULLRequest パラメーターを提供するかどうかに関係なく、NULLRequestOptions パラメーターを指定できます。たとえば、RequestOptions パラメーターを使用してタイムアウト値を指定できます。

USB 文字列記述子の詳細については、USB の仕様を参照してください。

WdfUsbTargetDeviceQueryString メソッドと USB I/O ターゲットの詳細については、「USB I/O ターゲットの」を参照してください。

例

次のコード例では、WdfUsbTargetDeviceQueryString を呼び出して必要なバッファーサイズを取得し、WdfMemoryCreate 呼び出してメモリオブジェクトとバッファーを作成した後、WdfUsbTargetDeviceQueryString を再度呼び出して、USB デバイス記述子から製造元の名前文字列 (0x0409) を取得します。 (ドライバーは、以前にドライバー定義のコンテキスト空間に記述子を格納しました。

PMY_DEVICE_CONTEXT  myDeviceContext;
USHORT  numCharacters;
PUSHORT  stringBuf;
WDFMEMORY  memoryHandle;

myDeviceContext = GetDeviceContext(device);

status = WdfUsbTargetDeviceQueryString(
                                       myDeviceContext->UsbTargetDevice,
                                       NULL,
                                       NULL,
                                       NULL,
                                       &numCharacters,
                                       myDeviceContext->UsbDeviceDescr.iManufacturer,
                                       0x0409
                                       );

ntStatus = WdfMemoryCreate(
                           WDF_NO_OBJECT_ATTRIBUTES,
                           NonPagedPool,
                           POOL_TAG,
                           numCharacters * sizeof(WCHAR),
                           &memoryHandle,
                           (PVOID)&stringBuf
                           );
if (!NT_SUCCESS(ntStatus)) {
    return ntStatus;
}
status = WdfUsbTargetDeviceQueryString(
                                       myDeviceContext->UsbTargetDevice,
                                       NULL,
                                       NULL,
                                       stringBuf,
                                       &numCharacters,
                                       myDeviceContext->UsbDeviceDescr.iManufacturer,
                                       0x0409
                                       );

必要条件

要件	価値
ターゲットプラットフォームの	万国
最小 KMDF バージョン	1.0
UMDF の最小バージョンをする	2.0
ヘッダー	wdfusb.h (Wdfusb.h を含む)
ライブラリ	Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則をする	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExp usbKmdfIrql(kmdf), usbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

次の方法で共有

WdfUsbTargetDeviceQueryString 関数 (wdfusb.h)

構文

パラメーター

戻り値

備考

例

必要条件

関連項目

フィードバック

その他のリソース