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

Статья
03/01/2024

Подпрограмма DpWmiExecuteMethod выполняет метод, связанный с блоком данных. Эта подпрограмма является необязательной.

Синтаксис

WMI_EXECUTE_METHOD_CALLBACK WmiExecuteMethodCallback;

NTSTATUS WmiExecuteMethodCallback(
  [in]      PDEVICE_OBJECT DeviceObject,
  [in]      PIRP Irp,
  [in]      ULONG GuidIndex,
  [in]      ULONG InstanceIndex,
  [in]      ULONG MethodId,
  [in]      ULONG InBufferSize,
  [in]      ULONG OutBufferSize,
  [in, out] PUCHAR Buffer
)
{...}

Параметры

[in] DeviceObject

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

[in] Irp

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

[in] GuidIndex

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

[in] InstanceIndex

Если блок, указанный в GuidIndex , содержит несколько экземпляров, InstanceIndex задает отсчитываемое от нуля значение индекса, идентифицирующее экземпляр.

[in] MethodId

Указывает идентификатор выполняемого метода. Драйвер определяет идентификатор метода как элемент в блоке данных.

[in] InBufferSize

Указывает размер входных данных в байтах. Если входные данные отсутствуют, значение InBufferSize равно нулю.

[in] OutBufferSize

Указывает количество байтов, доступных в буфере для выходных данных.

[in, out] Buffer

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

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

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

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

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

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

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

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

После выполнения метода и записи всех выходных данных в буфер драйвер вызывает WmiCompleteRequest для выполнения запроса.

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

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

Требования

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

См. также раздел

IRP_MN_EXECUTE_METHOD

WMILIB_CONTEXT

WmiCompleteRequest

WmiSystemControl

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