Функция WdfIoTargetAllocAndQueryTargetProperty (wdfiotarget.h)

Статья
03/22/2025

[Применимо только к KMDF]

Метод WdfIoTargetAllocAndQueryTargetProper ty выделяет буфер и извлекает указанное свойство устройства для указанного целевого объекта ввода-вывода.

Синтаксис

NTSTATUS WdfIoTargetAllocAndQueryTargetProperty(
  [in]           WDFIOTARGET              IoTarget,
  [in]           DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]           POOL_TYPE                PoolType,
  [in, optional] PWDF_OBJECT_ATTRIBUTES   PropertyMemoryAttributes,
  [out]          WDFMEMORY                *PropertyMemory
);

Параметры

[in] IoTarget

Дескриптор локального или удаленного целевого объекта ввода-вывода, полученного из предыдущего вызова WdfDeviceGetIoTarget или WdfIoTargetCreate или из метода, который предоставляет специализированный целевой объект ввода-вывода.

[in] DeviceProperty

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

[in] PoolType

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

[in, optional] PropertyMemoryAttributes

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

[out] PropertyMemory

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

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

WdfIoTargetAllocAndQueryTargetProperty возвращает STATUS_SUCCESS, если операция завершится успешно. В противном случае этот метод может вернуть одно из следующих значений:

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

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

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

Замечания

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

Дополнительные сведения о WdfIoTargetAllocAndQueryTargetPropertyсм. в получении сведений об общем целевом объекте ввода-вывода.

Дополнительные сведения о целевых объектах ввода-вывода см. в разделе Использование целевых объектов ввода-вывода.

Примеры

В следующем примере кода вызывается WdfIoTargetAllocAndQueryTargetProperty для получения свойства DevicePropertyFriendlyName. После возврата WdfIoTargetAllocAndQueryTargetProper ty драйвер может вызвать WdfMemoryGetBuffer, чтобы получить указатель на буфер, содержащий строку имени.

WDFMEMORY  targetName;
NTSTATUS  status;

status = WdfIoTargetAllocAndQueryTargetProperty(
                                                Target,
                                                DevicePropertyFriendlyName,
                                                NonPagedPool,
                                                WDF_NO_OBJECT_ATTRIBUTES,
                                                &targetName
                                                );

Требования

Требование	Ценность
целевая платформа	универсальный
минимальная версия KMDF	1.0
Заголовок	wdfiotarget.h (include Wdf.h)
Библиотека	Wdf01000.sys (см. управление версиями библиотеки Платформы).)
IRQL	PASSIVE_LEVEL
правил соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)