функция обратного вызова 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 или соответствующий код ошибки, например следующий:

Замечания

WMI вызывает процедуру драйвера DpWmiExecuteMethod после вызова драйвера WmiSystemControl в ответ на запрос IRP_MN_EXECUTE_METHOD.

Если драйвер реализует подпрограмму 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, является допустимым идентификатором для указанного блока данных, и что вызывающий объект разрешен выполнять метод.
Убедитесь, что буфер и InBufferSize описать буфер, который достаточно велик, чтобы содержать входные параметры указанного метода, включая заполнение при необходимости, и убедитесь, что входные параметры допустимы.
Убедитесь, что буфер и OutBufferSize описать буфер, который достаточно велик для получения выходных данных указанного метода, включая заполнение при необходимости.

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

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

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

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

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