WdfUsbTargetDeviceAllocAndQueryString 関数 (wdfusb.h)

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

[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を返します。それ以外の場合、このメソッドは次のいずれかの値を返すことができます。

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

このメソッドは、他の 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)