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_DESCRIPTORUSB_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)

こちらもご覧ください

USB_CONFIGURATION_DESCRIPTOR

USB_DEVICE_DESCRIPTOR

USB_INTERFACE_DESCRIPTOR

WDF_OBJECT_ATTRIBUTES

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceQueryString