WdfUsbTargetDeviceQueryString 関数 (wdfusb.h)
[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を返します。 それ以外の場合、このメソッドは次のいずれかの値を返すことができます。
リターン コード | 説明 |
---|---|
|
無効なパラメーターが検出されました。 |
|
メモリ バッファーを割り当てませんでした。 |
|
USB デバイスから無効な記述子が返されました。 |
|
指定されたバッファーが小さすぎます。 |
このメソッドは、他の NTSTATUS 値を返す場合もあります。
ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。
注釈
ドライバーは、次の手順を使用して WdfUsbTargetDeviceQueryString を 2 回呼び出す必要があります。
- 文字列ポインターを NULL に設定して、NumCharacters パラメーターが指すアドレスに必要なバッファー サイズを WdfUsbTargetDeviceQueryString が返すようにします。
- 要求された文字列内の Unicode 文字の数を保持するバッファー領域を割り当てます。 たとえば、ドライバーが ExAllocatePoolWithTag を呼び出してバッファーを割り当てる場合や、 WdfMemoryCreate を呼び出してフレームワーク メモリ オブジェクトを作成する場合があります。
- WdfUsbTargetDeviceQueryString をもう一度呼び出し、String 値を新しいバッファーへのポインターに設定し、NumCharacters をバッファーの長さ (つまり、バイト長ではなく 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) |
こちらもご覧ください
フィードバック
https://aka.ms/ContentUserFeedback」を参照してください。
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「フィードバックの送信と表示