Функция WdfUsbTargetDeviceQueryString (wdfusb.h)
[Применимо к 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, если операция выполнена успешно. В противном случае этот метод может вернуть одно из следующих значений:
Возвращаемый код | Описание |
---|---|
|
Обнаружен недопустимый параметр. |
|
Не удалось выделить буфер памяти. |
|
USB-устройство вернуло недопустимый дескриптор. |
|
Предоставленный буфер слишком мал. |
Этот метод также может возвращать другие значения NTSTATUS.
Ошибка возникает, если драйвер предоставляет недопустимый дескриптор объекта.
Замечания
Драйверы должны вызывать WdfUsbTargetDeviceQueryString дважды, выполнив следующие действия:
- Задайте указатель string на NULL, чтобы WdfUsbTargetDeviceQueryString вернет требуемый размер буфера в адресе, на который указывает параметр NumCharact ers.
- Выделите буферное пространство для хранения количества символов Юникода, которые находятся в запрошенной строке. Например, драйвер может вызвать ExAllocatePoolWithTag для выделения буфера или вызвать WdfMemoryCreate для создания объекта памяти платформы.
- Снова вызовите WdfUsbTargetDeviceQueryString, установив значение String указатель на новый буфер и задав NumCharacters длину буфера (то есть число символов Юникода, а не длину байтов).
Если драйвер задает значение, отличное от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) |