Функция WdfIoTargetQueryTargetProperty (wdfiotarget.h)
[Применяется только к KMDF]
Метод WdfIoTargetQueryTargetProperty извлекает указанное свойство устройства для указанного целевого объекта ввода-вывода.
Синтаксис
NTSTATUS WdfIoTargetQueryTargetProperty(
[in] WDFIOTARGET IoTarget,
[in] DEVICE_REGISTRY_PROPERTY DeviceProperty,
[in] ULONG BufferLength,
[out, optional] PVOID PropertyBuffer,
[out] PULONG ResultLength
);
Параметры
[in] IoTarget
Дескриптор для локального или удаленного целевого объекта ввода-вывода, полученного при предыдущем вызове WdfDeviceGetIoTarget или WdfIoTargetCreate, или из метода, предоставленного специализированным целевым объектом ввода-вывода.
[in] DeviceProperty
Значение типа DEVICE_REGISTRY_PROPERTY, определяющее извлекаемое свойство устройства.
[in] BufferLength
Размер (в байтах) буфера, на который указывает PropertyBuffer .
[out, optional] PropertyBuffer
Указатель на буфер, выделенный вызывающим объектом, который получает сведения о запрошенном свойстве устройства. Этот указатель может иметь значение NULL , если BufferLength равно нулю.
[out] ResultLength
Указатель на расположение, которое при возврате содержит размер (в байтах) сведений, которые WdfIoTargetQueryTargetProperty хранятся в буфере, на который указывает PropertyBuffer . Если WdfIoTargetQueryTargetProperty возвращает STATUS_BUFFER_TOO_SMALL, это расположение получает требуемый размер буфера.
Возвращаемое значение
WdfIoTargetQueryTargetProperty возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае этот метод может вернуть одно из следующих значений:
| Код возврата | Описание |
|---|---|
|
Буфер, на который указывает параметр PropertyBuffer , слишком мал для получения запрошенной информации. |
|
Недопустимое значение, указанное параметром DeviceProperty . |
|
Драйверы устройства еще не сообщили о свойствах устройства. |
Этот метод также может возвращать другие значения NTSTATUS.
Ошибка проверка возникает, если драйвер предоставляет недопустимый дескриптор объекта.
Комментарии
Прежде чем драйверы получат данные свойств устройства, они обычно вызывают метод WdfIoTargetQueryTargetProperty , чтобы получить необходимый размер буфера. Для некоторых свойств размер данных может меняться между возвратом требуемого размера и повторным вызовом WdfIoTargetQueryTargetProperty . Поэтому драйверы должны вызывать WdfIoTargetQueryTargetProperty внутри цикла, который выполняется до тех пор, пока состояние возврата не будет STATUS_BUFFER_TOO_SMALL.
Вместо вызова WdfIoTargetQueryTargetProperty драйвер может вызвать WdfIoTargetAllocAndQueryTargetProperty, который выделяет буфер и помещает сведения о свойствах в буфер.
Дополнительные сведения о WdfIoTargetQueryTargetProperty см. в разделе Получение сведений об общем целевом объекте ввода-вывода.
Дополнительные сведения о целевых объектах ввода-вывода см. в разделе Использование целевых объектов ввода-вывода.
Примеры
В следующем примере кода получается свойство DevicePropertyUINumber устройства. В примере вызывается WdfIoTargetQueryTargetProperty вместо WdfIoTargetAllocAndQueryTargetProperty , так как длина номера пользовательского интерфейса известна.
ULONG targetUINumber, resultLength;
NTSTATUS status;
status = WdfIoTargetQueryTargetProperty(
target,
DevicePropertyUINumber,
sizeof(targetNumber),
&targetUINumber,
&resultLength
);
Требования
| Требование | Значение |
|---|---|
| Целевая платформа | Универсальное |
| Минимальная версия KMDF | 1,0 |
| Верхняя часть | wdfiotarget.h (включая Wdf.h) |
| Библиотека | Wdf01000.sys (см. раздел Управление версиями библиотеки платформы). |
| IRQL | PASSIVE_LEVEL |
| Правила соответствия DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |