WdfUsbTargetDeviceQueryString 関数 (wdfusb.h)

[KMDF と UMDF に適用]

WdfUsbTargetDeviceQueryString メソッドは、指定された USB デバイスと記述子インデックス値に関連付けられている Unicode 文字列を取得します。

構文

NTSTATUS WdfUsbTargetDeviceQueryString(
  [in]            WDFUSBDEVICE              UsbDevice,
  [in, optional]  WDFREQUEST                Request,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [out, optional] PUSHORT                   String,
  [in, out]       PUSHORT                   NumCharacters,
  [in]            UCHAR                     StringIndex,
  [in, optional]  USHORT                    LangID
);

パラメーター

[in] UsbDevice

WdfUsbTargetDeviceCreateWithParametersへの以前の呼び出しから取得された USB デバイス オブジェクトへのハンドル。

[in, optional] Request

フレームワーク要求オブジェクトへのハンドル。 このパラメーターは省略可能であり、NULLできます。 詳細については、次の「解説」セクションを参照してください。

[in, optional] RequestOptions

要求のオプションを指定する呼び出し元によって割り当てられた WDF_REQUEST_SEND_OPTIONS 構造体へのポインター。 このポインターは省略可能であり、NULLできます。 詳細については、次の「解説」セクションを参照してください。

[out, optional] String

要求された Unicode 文字列を受け取る呼び出し元によって割り当てられたバッファーへのポインター。 この文字列は、デバイスが NULL で終わる文字列を提供する場合にのみ NULL で終了します。 このポインターが NULL場合、WdfUsbTargetDeviceQueryString は、NumCharacters が指す位置に必要なバッファー サイズ (つまり、Unicode 文字の必要な数) 返します。

[in, out] NumCharacters

呼び出し元によって割り当てられた変数へのポインター。 呼び出し元は、バッファーが保持できる Unicode 文字の数を指定します。 WdfUsbTargetDeviceQueryString が返されると、変数は、文字列 バッファーが受け取る Unicode 文字列内にある文字数 (NULL ターミネータを含む) を受け取ります。

[in] StringIndex

Unicode 文字列を識別するインデックス値。 このインデックス値は、USB_DEVICE_DESCRIPTOR、USB_CONFIGURATION_DESCRIPTOR、または USB_INTERFACE_DESCRIPTOR 構造体から取得されます。

[in, optional] LangID

言語識別子。 この識別子が指定する言語の Unicode 文字列が取得されます。 デバイスでサポートされている言語識別子の取得については、USB 仕様を参照してください。

戻り値

WdfUsbTargetDeviceQueryString は、操作が成功した場合にSTATUS_SUCCESSを返します。 それ以外の場合、このメソッドは次のいずれかの値を返すことができます。

このメソッドは、他の NTSTATUS 値を返す場合もあります。

ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。

備考

ドライバーは、次の手順 使用して、WdfUsbTargetDeviceQueryString を 2 回呼び出す必要があります。

• 文字列 ポインター NULLに設定して、WdfUsbTargetDeviceQueryString が、NumCharacters パラメーターが指すアドレスに必要なバッファー サイズを返すようにします。
• 要求された文字列内の Unicode 文字の数を保持するバッファー領域を割り当てます。 たとえば、ドライバーは ExAllocatePoolWithTag 呼び出してバッファーを割り当てたり、WdfMemoryCreate 呼び出してフレームワーク メモリ オブジェクトを作成したりする場合があります。
• WdfUsbTargetDeviceQueryString を再度呼び出し、文字列 値を新しいバッファーへのポインターに設定し、NumCharacters バッファーの長さ (つまり、バイト長ではなく Unicode 文字の数) に を設定します。

ドライバーが Request パラメーターに対して非NULL 値を指定した場合、フレームワークは指定された要求オブジェクトを使用し、別のドライバー スレッドは、必要に応じて、WdfRequestCancelSentRequestを呼び出して、文字列クエリ要求のキャンセルを試みることができます。 ドライバーが 要求の NULL 値を指定する場合、フレームワークは、ドライバーが取り消すことができない内部要求オブジェクトを使用します。

ドライバーは、以外の NULL または NULLRequest パラメーターを提供するかどうかに関係なく、NULLRequestOptions パラメーターを指定できます。 たとえば、RequestOptions パラメーターを使用してタイムアウト値を指定できます。

USB 文字列記述子の詳細については、USB の仕様を参照してください。

WdfUsbTargetDeviceQueryString メソッドと USB I/O ターゲットの詳細については、「USB I/O ターゲットの」を参照してください。

例

次のコード例では、WdfUsbTargetDeviceQueryString を呼び出して必要なバッファー サイズを取得し、WdfMemoryCreate 呼び出してメモリ オブジェクトとバッファーを作成した後、WdfUsbTargetDeviceQueryString を再度呼び出して、USB デバイス記述子から製造元の名前文字列 (0x0409) を取得します。 (ドライバーは、以前にドライバー定義のコンテキスト空間に記述子を格納しました。

PMY_DEVICE_CONTEXT  myDeviceContext;
USHORT  numCharacters;
PUSHORT  stringBuf;
WDFMEMORY  memoryHandle;

myDeviceContext = GetDeviceContext(device);

status = WdfUsbTargetDeviceQueryString(
                                       myDeviceContext->UsbTargetDevice,
                                       NULL,
                                       NULL,
                                       NULL,
                                       &numCharacters,
                                       myDeviceContext->UsbDeviceDescr.iManufacturer,
                                       0x0409
                                       );

ntStatus = WdfMemoryCreate(
                           WDF_NO_OBJECT_ATTRIBUTES,
                           NonPagedPool,
                           POOL_TAG,
                           numCharacters * sizeof(WCHAR),
                           &memoryHandle,
                           (PVOID)&stringBuf
                           );
if (!NT_SUCCESS(ntStatus)) {
    return ntStatus;
}
status = WdfUsbTargetDeviceQueryString(
                                       myDeviceContext->UsbTargetDevice,
                                       NULL,
                                       NULL,
                                       stringBuf,
                                       &numCharacters,
                                       myDeviceContext->UsbDeviceDescr.iManufacturer,
                                       0x0409
                                       );

必要条件

関連項目

USB_CONFIGURATION_DESCRIPTOR

USB_DEVICE_DESCRIPTOR

USB_INTERFACE_DESCRIPTOR

WDF_REQUEST_SEND_OPTIONS

WdfRequestCancelSentRequest

WdfUsbTargetDeviceAllocAndQueryString

WdfUsbTargetDeviceCreateWithParameters