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

Статья
07/16/2024

[Применимо к 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, если он указан) в строке Юникода, которую получает буфер string.

[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.

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

Замечания

Драйверы должны вызывать WdfUsbTargetDeviceQueryString дважды, выполнив следующие действия:

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

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

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

Драйвер может указать параметр, отличный отNULLRequestOptions, предоставляет ли драйвер параметрNULL или параметр NULLRequest. Например, можно использовать параметр 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 (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)