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 値を返す場合もあります。
ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。
注釈
ドライバーが文字列記述子を取得するために 1 回だけ呼び出す必要がある WdfUsbTargetDeviceAllocAndQueryString メソッドは、文字列を取得するために 2 回呼び出す必要がある WdfUsbTargetDeviceQueryString メソッドの代わりに使用されます。
メソッドは、指定された 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 |
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) |