функция обратного вызова WMI_FUNCTION_CONTROL_CALLBACK (wmilib.h)

Статья
08/08/2023

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

Синтаксис

WMI_FUNCTION_CONTROL_CALLBACK WmiFunctionControlCallback;

NTSTATUS WmiFunctionControlCallback(
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PIRP Irp,
  [in] ULONG GuidIndex,
  [in] WMIENABLEDISABLECONTROL Function,
  [in] BOOLEAN Enable
)
{...}

Параметры

[in] DeviceObject

Указатель на структуру WDM драйвера DEVICE_OBJECT .

[in] Irp

Указатель на IRP.

[in] GuidIndex

Задает блок данных путем предоставления отсчитываемого от нуля индекса в список идентификаторов GUID, предоставленных драйвером в структуре WMILIB_CONTEXT , переданной в WmiSystemControl.

[in] Function

Указывает, что следует включать или отключать. WmiEventControl указывает на событие, а WmiDataBlockControl указывает на сбор данных для блока, который был зарегистрирован как дорогостоящий для сбора (то есть блок, для которого набор драйверов WMIREG_FLAG_EXPENSIVE в разделе Флаги структуры WMIGUIDREGINFO , используемой для регистрации блока).

[in] Enable

Указывает значение TRUE , чтобы включить сбор данных или события, или значение FALSE , чтобы отключить его.

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

DpWmiFunctionControl возвращает STATUS_SUCCESS или соответствующее состояние ошибки, например:

Если драйвер реализует подпрограмму DpWmiFunctionControl , драйвер должен поместить адрес подпрограммы в член WmiFunctionControlструктуры WMILIB_CONTEXT , которую он передает WmiSystemControl. Если драйвер не реализует подпрограмму DpWmiFunctionControl , он должен задать для WmiFunctionControlзначение NULL. В последнем случае WMI возвращает STATUS_SUCCESS вызывающей объекту.

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

Убедитесь, что значение GuidIndex находится в диапазоне от нуля до GuidCount-1 на основе элемента GuidCountструктуры WMILIB_CONTEXT .
Убедитесь, что драйвер не помечает указанный блок данных для удаления. Если драйвер недавно указал флаг WMIREG_FLAG_REMOVE_GUID в структуре WMIGUIDREGINFO , содержащейся в структуре WMILIB_CONTEXT , до удаления может быть доставлен дополнительный запрос.

Драйверу не нужно проверка, включены ли события или сбор данных для блока, так как WMI отправляет один запрос на включение, когда первый потребитель данных включает блок, и отправляет один запрос на отключение, когда последний потребитель данных отключает блок. WMI не вызывает DpWmiFunctionControl , чтобы включить блок без промежуточного вызова для его отключения.

После включения или отключения сбора событий или данных для блока драйвер вызывает WmiCompleteRequest для выполнения запроса.

Эта подпрограмма может быть выстраимаемой.

Дополнительные сведения о реализации этой процедуры см. в статье Вызов WmiSystemControl для обработки WMI IRP.

Требования

Требование	Значение
Целевая платформа	Персональный компьютер
Верхняя часть	wmilib.h (включая Wmilib.h)
IRQL	Вызывается на PASSIVE_LEVEL.