Функция WdfDeviceQueryProperty (wdfdevice.h)

Статья
08/08/2023

[Применимо к KMDF и UMDF]

Метод WdfDeviceQueryProperty извлекает указанное свойство устройства.

Синтаксис

NTSTATUS WdfDeviceQueryProperty(
  [in]  WDFDEVICE                Device,
  [in]  DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]  ULONG                    BufferLength,
  [out] PVOID                    PropertyBuffer,
  [out] PULONG                   ResultLength
);

Параметры

[in] Device

Дескриптор объекта устройства платформы.

[in] DeviceProperty

Перечислитель DEVICE_REGISTRY_PROPERTY, который определяет извлекаемое свойство устройства.

[in] BufferLength

Размер (в байтах) буфера, на который указывает PropertyBuffer.

[out] PropertyBuffer

Предоставленный вызывающим объектом указатель на буфер, выделенный вызывающим объектом, который получает запрошенные сведения. Указатель может иметь значение NULL , если параметр BufferLength равен нулю.

[out] ResultLength

Указанное вызывающей стороной расположение, которое при возврате содержит размер в байтах сведений, хранящихся методом в PropertyBuffer. Если возвращаемое значение функции равно STATUS_BUFFER_TOO_SMALL, это расположение получает требуемый размер буфера.

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

Если операция выполнена успешно, WdfDeviceQueryProperty возвращает STATUS_SUCCESS. К дополнительным возвращаемым значениям относятся:

Код возврата	Описание
STATUS_BUFFER_TOO_SMALL	Предоставленный буфер слишком мал для получения информации.
STATUS_INVALID_PARAMETER_2	Указанное недопустимое значение DeviceProperty
STATUS_INVALID_DEVICE_REQUEST	Драйверы устройства еще не сообщили о свойствах устройства.

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

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

Перед получением данных свойств устройства драйверы обычно вызывают метод WdfDeviceQueryProperty только для получения требуемого размера буфера. Для некоторых свойств размер данных может меняться между возвратом требуемого размера и повторным вызовом драйвера WdfDeviceQueryProperty . Поэтому драйверы должны вызывать WdfDeviceQueryProperty внутри цикла, который выполняется до тех пор, пока состояние возврата не STATUS_BUFFER_TOO_SMALL.

WdfDeviceQueryProperty рекомендуется использовать только в том случае, если требуемый размер буфера известен и неизменяем, так как в этом случае драйвер должен вызывать WdfDeviceQueryProperty только один раз. Если требуемый размер буфера неизвестен или отличается, драйвер должен вызвать WdfDeviceAllocAndQueryProperty.

Кроме того, можно использовать WdfDeviceQueryPropertyEx для доступа к свойствам устройства, предоставляемым через модель унифицированных свойств.

Примеры

В следующем примере кода получается свойство DevicePropertyBusTypeGuid устройства. В примере вызывается WdfDeviceQueryProperty вместо WdfDeviceAllocAndQueryProperty , так как длина GUID известна.

GUID  busTypeGuid;
ULONG  resultLength = 0;
NTSTATUS  status;

status = WdfDeviceQueryProperty( 
                                device,
                                DevicePropertyBusTypeGuid,
                                sizeof(GUID),
                                (PVOID)&busTypeGuid,
                                &resultLength
                                );

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Минимальная версия UMDF	2,0
Верхняя часть	wdfdevice.h (включая Wdf.h)
Библиотека	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

См. также раздел

WdfDeviceAllocAndQueryProperty

WdfFdoInitQueryProperty

Поделиться через