WMI_EXECUTE_METHOD_CALLBACK callback function (wmilib.h)

Article
10/21/2021

The DpWmiExecuteMethod routine executes a method associated with a data block. This routine is optional.

Syntax

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
)
{...}

Parameters

[in] DeviceObject

Pointer to the driver's WDM DEVICE_OBJECT structure.

[in] Irp

Pointer to the IRP.

[in] GuidIndex

Specifies the data block by supplying a zero-based index into the list of GUIDs that the driver provided in the WMILIB_CONTEXT structure it passed to WmiSystemControl.

[in] InstanceIndex

If the block specified by GuidIndex has multiple instances, InstanceIndex specifies a zero-based index value that identifies the instance.

[in] MethodId

Specifies the ID of the method to execute. The driver defines the method ID as an item in a data block.

[in] InBufferSize

Indicates the size in bytes of the input data. If there is no input data, InBufferSize is zero.

[in] OutBufferSize

Indicates the number of bytes available in the buffer for output data.

[in, out] Buffer

Pointer to a buffer that holds input data, if any, and receives output data, if any, for the method. If the buffer is too small to receive all of the output data, the driver returns STATUS_BUFFER_TOO_SMALL and calls WmiCompleteRequest with the size required.

Return value

DpWmiExecuteMethod returns STATUS_SUCCESS or an appropriate error code such as the following:

Remarks

WMI calls a driver's DpWmiExecuteMethod routine after the driver calls WmiSystemControl in response to an IRP_MN_EXECUTE_METHOD request.

If a driver implements a DpWmiExecuteMethod routine, the driver must place the routine's address in the ExecuteWmiMethod member of the WMILIB_CONTEXT structure that it passes to WmiSystemControl. If a driver does not implement a DpWmiExecuteMethod routine, it must set ExecuteWmiMethod to NULL. In the latter case, WMI returns STATUS_INVALID_DEVICE_REQUEST to the caller in response to any IRP_MN_EXECUTE_METHOD request.

The driver is responsible for validating all input arguments. Specifically, the driver must do the following:

Verify that the GuidIndex value is between zero and GuidCount-1, based on the GuidCount member of the WMILIB_CONTEXT structure.
Verify that the driver has not flagged the specified data block for removal. If the driver recently specified the WMIREG_FLAG_REMOVE_GUID flag in a WMIGUIDREGINFO structure that is contained in a WMILIB_CONTEXT structure, it is possible for an additional request to arrive before the removal occurs.
Verify that the InstanceIndex value is within the range of instance indexes that are supported by the driver for the data block.
Verify that the method identifier supplied by MethodId is a valid identifier for the specified data block, and that the caller is allowed to execute the method.
Verify that Buffer and InBufferSize describe a buffer that is large enough to contain the specified method's input parameters, including padding if necessary, and verify that the input parameters are valid.
Verify that Buffer and OutBufferSize describe a buffer that is large enough to receive the specified method's output data, including padding if necessary.

Do not assume the thread context is that of the initiating user-mode application—a higher-level driver might have changed it.

If the specified method performs an operation that causes data loss, such as fetching and resetting the contents of a set of counters, the driver should validate the output buffer size before performing the operation. That way, the driver can return STATUS_BUFFER_TOO_SMALL and allow the caller to resubmit the request with a larger buffer, without prematurely resetting the counters.

After executing the method and writing any output data to the buffer, the driver calls WmiCompleteRequest to complete the request.

This routine can be pageable.

For more information about implementing this routine, see Calling WmiSystemControl to Handle WMI IRPs.

Requirements

Requirement	Value
Target Platform	Desktop
Header	wmilib.h (include Wmilib.h)
IRQL	Called at PASSIVE_LEVEL.