WdfUsbTargetDeviceQueryString 函式（wdfusb.h）

發行項
07/16/2024

[適用於 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。否則，這個方法可以傳回下列其中一個值：

傳回碼	描述
STATUS_INVALID_PARAMETER	偵測到無效的參數。
STATUS_INSUFFICIENT_RESOURCES	無法配置記憶體緩衝區。
STATUS_DEVICE_DATA_ERROR	USB 裝置傳回無效的描述元。
STATUS_BUFFER_OVERFLOW	提供的緩衝區太小。

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

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

言論

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

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

WdfUsbTargetDeviceQueryString 找出指定的 USB 字串描述元，並將 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
                                       );

要求

要求	價值
目標平臺	普遍
最低 KMDF 版本	1.0
最低 UMDF 版本	2.0
標頭	wdfusb.h （包括 Wdfusb.h）
連結庫	Wdf01000.sys （KMDF）：WUDFx02000.dll （UMDF）
IRQL	PASSIVE_LEVEL
DDI 合規性規則	DriverCreate（kmdf），KmdfIrql（kmdf），KmdfIrql2（kmdf），KmdfIrqlExplicit（kmdf），UsbKmdfIrql（kmdf），UsbKmdfIrql2（kmdf），UsbKmdfIrqlExplicit（kmdf）