WdfUsbTargetDeviceAllocAndQueryString 函式（wdfusb.h）

發行項
02/07/2025

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

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

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

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

言論

WdfUsbTargetDeviceAllocAndQueryString 方法，您的驅動程式只需要呼叫一次才能取得字符串描述元，是 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
                                        );

要求

要求	價值
目標平臺	普遍
最低 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）