WdfUsbTargetDeviceQueryString 函式 (wdfusb.h)

發行項
02/29/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 傳回時，如果提供字串緩衝區所接收 Unicode 字串中的 Unicode 字串中，變數會接收包含 NULL 終止符的字元數) (。

[in] StringIndex

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

[in, optional] LangID

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

傳回值

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

傳回碼	Description
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 值，架構會使用驅動程式無法取消的內部要求物件。

不論驅動程式是否提供非 NULL 或NULL要求參數，您的驅動程式都可以指定非 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
                                       );

規格需求

需求	值
目標平台	Universal
最小 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)