Chris Cant - Writing Windows WDM Device Drivers

if (dx->PowerState>PowerDeviceD0) {

DebugPrintMsg("SetWmiDataBlock: Disabling power down: power up");

SendDeviceSetPower(dx, PowerDeviceD0);

}

}

return WmiCompleteRequest( fdo, Irp, STATUS_SUCCESS, 0, IO_NO_INCREMENT);

}

return FailWMIRequest(fdo, Irp, GuidIndex);

}

A SetWmiDataItem callback handles the setting of one data item in an instance. This routine is not called in Wdm3. Listing 12.8 shows how SetWmiDataItem calls FailWMIRequest to reject the WMI IRP. FailWMIRequest fails the IRP with STATUS_WMI_GUID_NOT_FOUND if an invalid GUID was given, or STATUS_INVALID_DEVICE_REQUEST otherwise.

Listing 12.8 SetWmiDataItem routine

NTSTATUS SetWmiDataItem(IN PDEVICE_OBJECT fdo, IN PIRP Irp, IN ULONG GuidIndex, IN ULONG InstanceIndex, IN ULONG DataltemId, IN ULONG BufferSize, IN PUCHAR PBuffer) {

DebugPrint("SetWmiDataItem: GuidIndex %d, InstanceIndex %d, DataItemId %d, BufferSize %d",

GuidIndex.InstanceIndex, DataItemId, BufferSize);

return FailWMIRequest(fdo, Irp, GuidIndex);

}

NTSTATUS FailWMIRequest(IN PDEVICE_OBJECT fdo, IN PIRP Irp, IN ULONG GuidIndex) {

DebugPrint("FailWMIRequest: GuidIndex %d",GuidIndex);

NTSTATUS status;

if (GuidIndex<0 || GuidIndex>=GUID_COUNT) status = STATUS_WMI_GUID_NOT_FOUND;

else status = STATUS_INVALID_DEVICE_REQUEST;

status = WmiCompleteRequest(fdo, Irp, status, 0, IO_NO_INCREMENT);

return status;

}

Listing 12.9 shows how I think the optional ExecuteWmiMethod routine should be implemented. As I stated earlier, I could not get mofcomp to compile the PowerDown method in the Wdm3Information WMI data block. Therefore, I have not so far been able to test this method.

Listing 12.9 ExecuteWmiMethod routine

NTSTATUS ExecuteWmiMethod(IN PDEVICE_OBJECT fdo, IN PIRP Irp, IN ULONG GuidIndex, IN ULONG InstanceIndex, IN ULONG MethodId, IN ULONG InBufferSize, IN ULONG OutBufferSize, IN OUT PUCHAR Buffer) {

DebugPrint("ExecuteWmiMethod: GuidIndex %d, InstanceIndex %d, "

"MethodId %d, InBufferSize %d OutBufferSize %d",

GuidIndex, InstanceIndex, MethodId, InBufferSize, OutBufferSize);

PWOM3_DEVICE_EXTENSION dx = (PWDM3_DEVICE_EXTENSION)fdo->DeviceExtension;

if (GuidIndex==WDM3_WMI_GUID_INDEX && MethodId==0) {

DebugPrintMsg("ExecuteWmiMethod: PowerDown method");

// Power Down

if (dx->PowerState

return WmiCompleteRequest(fdo, Irp, STATUS_SUCCESS, 0, IO_NO_INCREMENT);

}

return FailWMIRequest(fdo, Irp, GuidIndex);

}

To fire a WMI event, simply call WmiFireEvent , passing the relevant WMI event block GUID, the InstanceIndex, and any event data. WmiFireEvent makes the appropriate call to IoWmiWriteEvent .

The Wdm3 driver provides a helper function Wdm3FireEvent , shown in Listing 12.10. This takes a NULL-terminated wide string, formats it into a Wdm3Event message, and calls WmiFireEvent .

A user application must ask for events first by setting an Enable flag. This request arrives at the driver in its WmiFunctionControl optional callback routine. If the Function parameter is WmiEventControl , the new Enable setting is stored in the WMIEventEnabled flag in the device extension. WmiFunctionControl is also called to ask a driver to collect WMI data blocks that were marked as being expensive to collect.

The W MIEventEnabled flag is initially FALSE, which means that no events are generated. As I have found no way of registering for events, the Wdm3FireEvent and WmiFunctionControl functions have not been tested.

Listing 12.10 Wdm3FireEvent and WmiFunctionControl routines

void Wdm3FireEvent(IN PDEVICE_OBJECT fdo, wchar_t* Msg) {

DebugPrint("Wdm3FireEvent: Msg %S", Msg);

PWDM3_DEVICE_EXTENSION dx = (PWDM3_DEVICE_EXTENSION)fdo->DeviceExtension;

if (!dx->WMIEventEnabled) return;

// Get MsgLen in bytes

int MsgLen = 0;

wchar_t* Msg2 = Msg;

while (*Msg2++!=0) MsgLen += sizeof(wchar_t);

// Allocate event memory

PUSHORT pData = (PUSHORT)ExAllocatePool(NonPagedPool, MsgLen+2);

if (pData==NULL) return;

PUSHORT pData2 = pData;

*pData2++ = MsgLen;

RtlMoveMemory(pData2, Msg, MsgLen);

WmiFireEvent(fdo, (LPGUID)&WDM3_WMI_EVENT_GUID, 0, MsgLen+2, pData);

}

NTSTATUS WmiFunctionControl(IN PDEVICE_OBJECT fdo, IN PIRP Irp, IN ULONG GuidIndex, IN WMIENABLEDISABLECONTROL Function, IN BOOLEAN Enable) {

DebugPrint("WmiFunctionControl: GuidIndex %d, Function %d, Enable %d",

GuidIndex, Function, Enable);

PWDM3_DEVICE_EXTENSION dx = (PWDM3_DEVICE_EXTENSION)fdo->DeviceExtension;

if (GuidIndex==WDM3_WMI_EVENT_GUID_INDEX && Function==WmiEventControl) {

DebugPrint("WmiFunctionControl: Event enable %d", Enable);

dx->WMIEventEnabled = Enable;

return WmiCompleteRequest(fdo, Irp, STATUS_SUCCESS, 0, IO_NO_INCREMENT);

}

return FailWMIRequest(fdo, Irp, GuidIndex);

}

The WMl features of the Wdm3 driver can be tested in three ways. In all cases, the DebugPrint output of the checked build gives copious trace information about the requests as they happen.

The first thing I must say is that I could not get the driver to compile or run in Windows 98. I am sure that I could have got the Wdm3 driver to compile if I had copied the correct headers and libraries into the W98 DDK, but that did not seem appropriate. It is possible that the one test Windows 98 computer available had its WBEM/WMI runtime corrupted. In the Windows 2000 beta 2, I obtained an update to the WBEM/WMI SDK. Perhaps this update was not meant for Windows 98 and therefore messed up the runtime environment. Anyway, I was able to do the rest of my testing only in Windows 2000.

The MSPower_DeviceEnable WMI data block is used by the Device Manager to display the Power Management tab in the device properties box, as shown in Figure 10.3 in Chapter 10. It retrieves the Enable property, eventually in a call to QueryWmiDataBlock . If the user changes the setting, it is changed in SetWmiDataBlock when the device properties box is closed.

Alternatively, the standard WBEM Object Browser can be used to inspect the MSPower_ DeviceEnable or Wdm3Information WMI data blocks. Logon to the \Root\WMI namespace as the current user, select the Wdm3Information class, for instance, and select one of the Wdm3 device instances.

Figure 12.1 shows the Wdm3Information display for the Wdm3 device that has an instance name of Root\\Unknown\\0004_0 as its key property. The Wdm3Test application has been run, so the current buffer length is 4. The BufferFirstWord property has a decimal value of 2882400001, which is hex 0xabcdef01.