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

Статья
08/08/2023

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

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

Синтаксис

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 . После возврата WdfIoTargetAllocAndQueryTargetProperty драйвер может вызвать WdfMemoryGetBuffer , чтобы получить указатель на буфер, содержащий строку имени.

WDFMEMORY  targetName;
NTSTATUS  status;

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

Требования

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