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

Статья
02/07/2025

[Применимо к 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.

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

Замечания

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

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

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

Примеры

В следующем примере кода получается свойство device 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 (include Wdf.h)
библиотеки	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
правил соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

См. также

WdfDeviceAllocAndQueryProperty

WdfFdoInitQueryProperty

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