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

Статья
08/08/2023

[Относится к KMDF и UMDF]

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

Синтаксис

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

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

[in, optional] Request

Дескриптор объекта запроса платформы. Этот параметр является необязательным и может иметь значение NULL. Дополнительные сведения см. в разделе "Примечания".

[in, optional] RequestOptions

Указатель на структуру WDF_REQUEST_SEND_OPTIONS , выделенную вызывающим объектом, которая задает параметры для запроса. Этот указатель является необязательным и может иметь значение NULL. Дополнительные сведения см. в разделе "Примечания".

[out, optional] String

Указатель на буфер, выделенный вызывающим объектом, который получает запрошенную строку Юникода. Строка завершается null, только если устройство предоставляет строку, завершаемую null. Если этот указатель имеет значение NULL, WdfUsbTargetDeviceQueryString возвращает требуемый размер буфера (то есть необходимое количество символов Юникода) в расположении, на которое указывает NumCharacters .

[in, out] NumCharacters

Указатель на переменную, выделенную вызывающим объектом. Вызывающий объект предоставляет количество символов Юникода, которые может содержать буфер. При возврате WdfUsbTargetDeviceQueryString переменная получает количество символов (включая символ конца NULL, если он указан), которые находятся в строке Юникода, которую получает строковый буфер.

[in] StringIndex

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

[in, optional] LangID

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

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

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

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

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

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

Установите для указателя Stringзначение NULL, чтобы WdfUsbTargetDeviceQueryString возвращал требуемый размер буфера в адресе, на который указывает параметр NumCharacters .
Выделите буферное пространство для хранения количества символов Юникода, которые находятся в запрошенной строке. Например, драйвер может вызвать ExAllocatePoolWithTag , чтобы выделить буфер, или WdfMemoryCreate для создания объекта памяти платформы.
Снова вызовите WdfUsbTargetDeviceQueryString , задав для значения String указатель на новый буфер и задав NumCharacters длину буфера (т. е. количество символов Юникода, а не длину байтов).

WdfUsbTargetDeviceQueryString находит указанный дескриптор строки USB и копирует строку Юникода из дескриптора в предоставленный буфер.

Если драйвер задает для параметра Request значение, отличное от NULL, платформа использует указанный объект запроса, а другой поток драйвера при необходимости может вызвать WdfRequestCancelSentRequest, чтобы попытаться отменить строковый запрос. Если драйвер задает значение NULL для параметра Request, платформа использует внутренний объект запроса, который драйвер не может отменить.

Драйвер может указать параметр RequestOptions, отличный от NULL, независимо от того, предоставляет ли драйвер параметр запроса, отличный от NULL или null. Например, можно использовать параметр RequestOptions , чтобы указать значение времени ожидания.

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

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

Примеры

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

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)