WdfUsbTargetDeviceAllocAndQueryString 関数 (wdfusb.h)
[KMDF と UMDF に適用]
WdfUsbTargetDeviceAllocAndQueryString メソッドはバッファーを割り当て、指定された USB デバイスと記述子インデックス値に関連付けられている Unicode 文字列を取得します。
構文
NTSTATUS WdfUsbTargetDeviceAllocAndQueryString(
[in] WDFUSBDEVICE UsbDevice,
[in, optional] PWDF_OBJECT_ATTRIBUTES StringMemoryAttributes,
[out] WDFMEMORY *StringMemory,
[out, optional] PUSHORT NumCharacters,
[in] UCHAR StringIndex,
[in, optional] USHORT LangID
);
パラメーター
[in] UsbDevice
WdfUsbTargetDeviceCreateWithParametersへの以前の呼び出しから取得された USB デバイス オブジェクトへのハンドル。
[in, optional] StringMemoryAttributes
新しいメモリ オブジェクトの呼び出し元が指定した属性を含む呼び出し元によって割り当てられた WDF_OBJECT_ATTRIBUTES 構造体へのポインター。 このパラメーターは省略可能であり、WDF_NO_OBJECT_ATTRIBUTESできます。
[out] StringMemory
Unicode 文字列を含むメモリ オブジェクトへのハンドルを受け取る場所へのポインター。 この文字列は、デバイスが NULL で終わる文字列を提供する場合にのみ NULL で終了します。
[out, optional] NumCharacters
文字列記述子に含まれる文字数を受け取る場所へのポインター。 Unicode 文字列が NULL で終わる場合、この数値には NULL 文字が含まれます。 このパラメーターは省略可能であり、NULL できます。
[in] StringIndex
Unicode 文字列を識別するインデックス値。 このインデックス値は、USB_DEVICE_DESCRIPTOR、USB_CONFIGURATION_DESCRIPTOR、または USB_INTERFACE_DESCRIPTOR 構造体から取得されます。
[in, optional] LangID
言語識別子。 この識別子が指定する言語の Unicode 文字列が取得されます。 デバイスでサポートされている言語識別子の取得については、USB 仕様を参照してください。
戻り値
WdfUsbTargetDeviceAllocAndQueryString 、操作が成功した場合にSTATUS_SUCCESSを返します。 それ以外の場合、このメソッドは次のいずれかの値を返すことができます。
| リターン コード | 形容 |
|---|---|
|
無効なパラメーターが検出されました。 |
|
メモリ バッファーを割り当てませんでした。 |
|
USB デバイスから無効な記述子が返されました。 |
|
指定されたバッファーが小さすぎました。 |
このメソッドは、他のNTSTATUS 値を返す場合もあります。
ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。
備考
WdfUsbTargetDeviceAllocAndQueryString メソッドは、ドライバーが文字列記述子を取得するために 1 回だけ呼び出す必要がありますが、WdfUsbTargetDeviceQueryString メソッドの代わりに、文字列を取得するために 2 回呼び出す必要があります。
このメソッドは、指定された USB 文字列記述子を検索し、記述子からメモリ オブジェクトに Unicode 文字列をコピーし、メモリ オブジェクトにハンドルを返します。
WdfUsbTargetDeviceAllocAndQueryString 呼び出した後、ドライバーは StringMemory ハンドルを渡して、WdfMemoryGetBuffer を してメモリ オブジェクトの内容にアクセスできます。
USB 文字列記述子の詳細については、USB の仕様を参照してください。
WdfUsbTargetDeviceAllocAndQueryString メソッドと USB I/O ターゲットの詳細については、「USB I/O ターゲットを参照してください。
例
次のコード例では、WdfUsbTargetDeviceAllocAndQueryString を呼び出して、USB デバイス記述子から製造元の名前文字列 (米国英語 (0x0409) を取得します。 (ドライバーは、以前にドライバー定義のコンテキスト空間に記述子を格納しました。
PMY_DEVICE_CONTEXT myDeviceContext;
WDFMEMORY memoryHandle;
USHORT numCharacters;
myDeviceContext = GetDeviceContext(device);
status = WdfUsbTargetDeviceAllocAndQueryString(
myDeviceContext->UsbTargetDevice,
WDF_NO_OBJECT_ATTRIBUTES,
&memoryHandle,
&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) |
関連項目
WdfUsbTargetDeviceCreateWithParameters
WdfUsbTargetDeviceQueryString の