Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

WmiSystemControl routine

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,
  _Inout_  PIRP Irp,
  _Out_    PSYSCTL_IRP_DISPOSITION IrpDisposition
);

Parameters

WmiLibInfo [in]

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.

DeviceObject [in]

A pointer to the driver's DEVICE_OBJECT.

Irp [in, out]

A pointer to the IRP.

IrpDisposition [out]

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:

STATUS_INVALID_DEVICE_REQUEST
STATUS_WMI_GUID_NOT_FOUND
STATUS_WMI_INSTANCE_NOT_FOUND

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

Version

Available in Windows 2000 and later versions of Windows.

Header

Wmilib.h (include Wmilib.h)

Library

Wmilib.lib

IRQL

PASSIVE_LEVEL (see Remarks section)

DDI compliance rules

WmiComplete

See also

DpWmiExecuteMethod
DpWmiFunctionControl
DpWmiQueryDataBlock
DpWmiQueryReginfo
DpWmiSetDataBlock
DpWmiSetDataItem
IoCompleteRequest
IRP_MJ_SYSTEM_CONTROL
IRP_MN_REGINFO_EX
WMILIB_CONTEXT

 

 

Send comments about this topic to Microsoft

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.