WdfUsbTargetDeviceQueryString 関数 (wdfusb.h)

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

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

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

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

ドライバーは、NULL 以外の RequestOptions パラメーターを指定できます。これは、ドライバーが NULL 以外の要求パラメーターまたは NULL要求パラメーターを提供するかどうかです。たとえば、 RequestOptions パラメーターを使用してタイムアウト値を指定できます。

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

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

例

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

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
Header	wdfusb.h (Wdfusb.h を含む)
Library	Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則	DriverCreate(kmdf)、 KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)、 UsbKmdfIrql(kmdf)、 UsbKmdfIrql2(kmdf)、UsbKmdfIrqlExplicit(kmdf)