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

Статья
03/22/2025

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

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

Синтаксис

NTSTATUS WdfIoTargetQueryTargetProperty(
  [in]            WDFIOTARGET              IoTarget,
  [in]            DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]            ULONG                    BufferLength,
  [out, optional] PVOID                    PropertyBuffer,
  [out]           PULONG                   ResultLength
);

Параметры

[in] IoTarget

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

[in] DeviceProperty

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

[in] BufferLength

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

[out, optional] PropertyBuffer

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

[out] ResultLength

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

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

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

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

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

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

Замечания

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

Вместо вызова WdfIoTargetQueryTargetPropertyдрайвер может вызывать WdfIoTargetAllocAndQueryTargetProperty, который выделяет буфер и помещает сведения о свойстве в буфер.

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

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

Примеры

В следующем примере кода получается свойство DevicePropertyUINumber устройства. В примере вызывается WdfIoTargetQueryTargetProperty вместо WdfIoTargetAllocAndQueryTargetProperty, так как длина номера пользовательского интерфейса известна.

ULONG targetUINumber, resultLength;
NTSTATUS status;

status = WdfIoTargetQueryTargetProperty(
                                        target,
                                        DevicePropertyUINumber,
                                        sizeof(targetNumber),
                                        &targetUINumber,
                                        &resultLength
                                        );

Требования

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