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

Статья
02/07/2025

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

Метод WdfDeviceAllocAndQueryProperty выделяет буфер и извлекает указанное свойство устройства.

Синтаксис

NTSTATUS WdfDeviceAllocAndQueryProperty(
  [in]           WDFDEVICE                Device,
  [in]           DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]           POOL_TYPE                PoolType,
  [in, optional] PWDF_OBJECT_ATTRIBUTES   PropertyMemoryAttributes,
  [out]          WDFMEMORY                *PropertyMemory
);

Параметры

[in] Device

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

[in] DeviceProperty

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

[in] PoolType

Перечислитель POOL_TYPEтипа, указывающий тип памяти, который нужно выделить.

[in, optional] PropertyMemoryAttributes

Указатель на выделенную вызывающим WDF_OBJECT_ATTRIBUTES структуру, описывающую атрибуты объектов для объекта памяти, который будет выделена функцией. Этот параметр является необязательным и может быть WDF_NO_OBJECT_ATTRIBUTES.

[out] PropertyMemory

Указатель на типизированное расположение WDFMEMORY, которое получает дескриптор объекту памяти платформы.

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

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

Возвращаемый код	Описание
STATUS_INVALID_PARAMETER или STATUS_INVALID_PARAMETER_2	Указанное значение DeviceProperty недопустимо.
STATUS_INVALID_DEVICE_REQUEST	Драйверы устройства еще не сообщили о свойствах устройства.

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

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

Замечания

Метод WdfDeviceAllocAndQueryProperty определяет объем памяти, необходимый для хранения запрошенного свойства устройства. Он выделяет достаточно памяти для хранения данных и возвращает дескриптор в объект памяти платформы, описывающий выделенную память. Чтобы получить доступ к данным, драйвер может вызвать WdfMemoryGetBuffer.

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

Примеры

В следующем примере кода инициализируется структура WDF_OBJECT_ATTRIBUTES с атрибутами объекта памяти платформы, который платформа создаст для запрошенного свойства. Затем в примере вызывается WdfDeviceAllocAndQueryProperty для получения свойства DevicePropertyPhysicalDeviceObjectName. После WdfDeviceAllocAndQueryProperty драйвер может вызывать WdfMemoryGetBuffer, чтобы получить указатель на буфер, содержащий строку имени.

WDF_OBJECT_ATTRIBUTES  attributes;
NTSTATUS  status;
WDFDEVICE  device;
WDFMEMORY  memory;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = device;

status = WdfDeviceAllocAndQueryProperty(device,
                                        DevicePropertyPhysicalDeviceObjectName,
                                        NonPagedPool,
                                        &attributes,
                                        &memory
                                        );
if (!NT_SUCCESS(status)) {
    return STATUS_UNSUCCESSFUL;
}

Требования

Требование	Ценность
целевая платформа	Всеобщий
минимальная версия 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)

См. также

WdfDeviceQueryProperty

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