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 傳回時，變數會接收 String 緩衝區接收的 Unicode 字符串中的字元數（包括 NULL 終止符。

[in] StringIndex

識別 Unicode 字串的索引值。 這個索引值是從 USB_DEVICE_DESCRIPTOR、USB_CONFIGURATION_DESCRIPTOR或 USB_INTERFACE_DESCRIPTOR 結構取得。

[in, optional] LangID

語言標識碼。 系統會擷取此標識碼所指定語言的 Unicode 字串。 如需取得裝置支援的語言標識碼的相關信息，請參閱 USB 規格。

傳回值

如果作業成功，WdfUsbTargetDeviceQueryString 會傳回STATUS_SUCCESS。 否則，這個方法可以傳回下列其中一個值：

此方法也可能 傳回其他NTSTATUS 值。

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

言論

驅動程序應該使用下列步驟呼叫 WdfUsbTargetDeviceQueryString 兩次：

• 將 String 指標設定為 NULL，讓 WdfUsbTargetDeviceQueryString 會傳回 NumCharacters 參數指向的位址中所需的緩衝區大小。
• 配置緩衝區空間，以保存所要求字串中的 Unicode 字元數目。 例如，驅動程式可能會呼叫 ExAllocatePoolWithTag 來配置緩衝區，或者可能會呼叫 WdfMemoryCreate 來建立架構記憶體物件。
• 再次呼叫 WdfUsbTargetDeviceQueryString，將 String 值設定為新緩衝區的指標，並將 NumCharacters 為緩衝區的長度（也就是 Unicode 字元數目，而不是位元組長度）。

如果您的驅動程式為 Request 參數指定非NULL 值，架構會使用指定的要求物件，而另一個驅動程式線程可以視需要呼叫 WdfRequestCancelSentRequest，以嘗試取消字元串查詢要求。 如果驅動程式為 Request指定 NULL 值，則架構會使用驅動程式無法取消的內部要求物件。

您的驅動程式可以指定非NULLRequestOptions 參數、驅動程式提供非NULL 或 NULLRequest 參數。 例如，您可以使用 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