WmiSystemControl function (wmilib.h)
The WmiSystemControl routine is a dispatch routine for drivers that use WMI library support routines to handle WMI IRPs.
Syntax
NTSTATUS WmiSystemControl(
[in] PWMILIB_CONTEXT WmiLibInfo,
[in] PDEVICE_OBJECT DeviceObject,
[in, out] PIRP Irp,
[out] PSYSCTL_IRP_DISPOSITION IrpDisposition
);
Parameters
[in] WmiLibInfo
A pointer to a WMILIB_CONTEXT structure that contains registration information for a driver's data blocks and event blocks and defines entry points for the driver's WMI library callback routines.
[in] DeviceObject
A pointer to the driver's DEVICE_OBJECT.
[in, out] Irp
A pointer to the IRP.
[out] IrpDisposition
A pointer to an enumeration value of type SYSCTL_IRP_DISPOSITION that indicates how the IRP was handled. WmiSystemControl always sets this value, even when it returns a non-success NTSTATUS code.
SYSCTL_IRP_DISPOSITION is an enumeration in Wmilib.h and contains the following values:
IrpProcessed
The IRP was processed and possibly completed. If the driver's DpWmiXxx routine called by WmiSystemControl did not complete the IRP, the driver must call WmiCompleteRequest to complete the IRP after WmiSystemControl returns.
IrpNotCompleted
The IRP was processed but not completed, either because WMI detected an error and set up the IRP with an appropriate error code, or processed an IRP_MN_REGINFO or IRP_MN_REGINFO_EX request. The driver must complete the IRP by calling IoCompleteRequest.
IrpNotWmi
The IRP is not a WMI request (that is, WMI does not recognize the IRP's minor code). If the driver handles IRP_MJ_SYSTEM_CONTROL requests with this IRP_MN_XXX, it should handle the IRP; otherwise, the driver should forward the IRP to the next lower driver. If the driver is the lowest-level driver, then it must complete the IRP.
IrpForward
The IRP is targeted to another device object (that is, the device object pointer at Parameters.WMI.ProviderId in the IRP does not match the pointer passed by the driver in its call to IoWMIRegistrationControl). The driver must forward the IRP to the next lower driver. If the driver is the lowest-level driver, then it must complete the IRP.
Return value
WmiSystemControl returns STATUS_SUCCESS or one of the following error codes:
Remarks
When a driver receives an IRP_MJ_SYSTEM_CONTROL request with a WMI IRP minor code, it calls WmiSystemControl with a pointer to the driver's WMILIB_CONTEXT structure, a pointer to its device object, and a pointer to the IRP. The WMILIB_CONTEXT structure contains registration information for the driver's data blocks and event blocks and defines entry points for its WMI library callback routines.
WmiSystemControl confirms that the IRP is a WMI request and determines whether the block specified by the request is valid for the driver. If so, it processes the IRP by calling the appropriate DpWmiXxx entry point in the driver's WMILIB_CONTEXT structure. WMI is running at IRQL PASSIVE_LEVEL when it calls the driver's DpWmiXxx routine.
A driver must be running at IRQL PASSIVE_LEVEL when it forwards an IRP_MJ_SYSTEM_CONTROL request to the next-lower driver.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available in Windows 2000 and later versions of Windows. |
| Target Platform | Universal |
| Header | wmilib.h (include Wmilib.h) |
| Library | Wmilib.lib |
| IRQL | PASSIVE_LEVEL (see Remarks section) |
| DDI compliance rules | WmiComplete(wdm) |