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

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

要件

こちらもご覧ください

USB_CONFIGURATION_DESCRIPTOR

USB_DEVICE_DESCRIPTOR

USB_INTERFACE_DESCRIPTOR

WDF_OBJECT_ATTRIBUTES

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceQueryString