Функция WdfUsbTargetDeviceAllocAndQueryString (wdfusb.h)

Статья
02/07/2025

[Применимо к KMDF и UMDF]

Метод WdfUsbTargetDeviceAllocAndQueryString выделяет буфер, а затем получает строку Юникода, связанную с указанным USB-устройством и значением индекса дескриптора.

Синтаксис

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

Дескриптор объекта USB-устройства, полученный из предыдущего вызова WdfUsbTargetDeviceCreateWithParameters.

[in, optional] StringMemoryAttributes

Указатель на структуру, выделенную вызывающим объектом, WDF_OBJECT_ATTRIBUTES, которая содержит атрибуты, предоставленные вызывающим объектом памяти. Этот параметр является необязательным и может быть WDF_NO_OBJECT_ATTRIBUTES.

[out] StringMemory

Указатель на расположение, которое получает дескриптор объекта памяти, содержащего строку Юникода. Строка завершается значением NULL, только если устройство предоставляет строку, завершаемую значением NULL.

[out, optional] NumCharacters

Указатель на расположение, которое получает количество символов, содержащихся в дескрипторе строки. Если строка Юникода завершается null, этот номер включает символ NULL. Этот параметр является необязательным и может быть null.

[in] StringIndex

Значение индекса, определяющее строку Юникода. Это значение индекса получается из структуры USB_DEVICE_DESCRIPTOR, USB_CONFIGURATION_DESCRIPTORили USB_INTERFACE_DESCRIPTOR.

[in, optional] LangID

Идентификатор языка. Строка Юникода будет извлечена для языка, указанного этим идентификатором. Сведения о получении поддерживаемых идентификаторов языка устройства см. в спецификации USB.

Возвращаемое значение

WdfUsbTargetDeviceAllocAndQueryString возвращает STATUS_SUCCESS, если операция завершится успешно. В противном случае этот метод может вернуть одно из следующих значений:

Возвращаемый код	Описание
STATUS_INVALID_PARAMETER	Обнаружен недопустимый параметр.
STATUS_INSUFFICIENT_RESOURCES	Не удалось выделить буфер памяти.
STATUS_DEVICE_DATA_ERROR	USB-устройство вернуло недопустимый дескриптор.
STATUS_BUFFER_OVERFLOW	Предоставленный буфер слишком мал.

Этот метод также может возвращать другие значения NTSTATUS.

Ошибка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Замечания

Метод WdfUsbTargetDeviceAllocAndQueryString, который драйвер должен вызывать только один раз для получения дескриптора строки, является альтернативой методу WdfUsbTargetDeviceQueryString, который необходимо вызывать дважды для получения строки.

Метод находит указанный дескриптор строки USB, копирует строку Юникода из дескриптора в объект памяти и возвращает дескриптор в объект памяти.

После вызова WdfUsbTargetDeviceAllocAndQueryStringдрайвер может передать дескриптор StringMemoryWdfMemoryGetBuffer для доступа к содержимому объекта памяти.

Дополнительные сведения о дескрипторах строк USB см. в спецификации USB.

Дополнительные сведения о методе WdfUsbTargetDeviceAllocAndQueryString и целевых объектах usb-ввода-вывода см. в целевых объектов USB-ввода-вывода.

Примеры

Следующий пример кода вызывает WdfUsbTargetDeviceAllocAndQueryString для получения строки имени производителя в США английском языке (0x0409) из дескриптора USB-устройства. (Драйвер, ранее хранимый дескриптор в пространстве контекста, определяемом драйвером.)

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 (include 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)