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

Статья
08/08/2023

[Относится к 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 драйвер может передать дескриптор StringMemoryв WdfMemoryGetBuffer для доступа к содержимому объекта памяти.

Дополнительные сведения о дескрипторов строки 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 (включая 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)