Writing Windows WDM Device Drivers

  Msg.Format('DBT_CONFIGCHANGECANCELED');
  break;
 case DBT_CONFIGCHANGED:
  Msg.Format('DBT_CONFIGCHANGED');
  break;
 case DBT_CUSTOMEVENT:
  Msg.Format('DBT_CUSTOMEVENT');
  break;
 case DBT_DEVICEARRIVAL:
  Msg.Format('DBT_DEVICEARRIVAL');
  break;
 case DBT_DEVICEQUERYREMOVE:
  Msg.Format('DBT_DEVICEQUERYREMOVE');
  break;
 case DBT_DEVICEQUERYREMOVEFAILED:
  Msg.Format('DBT_DEVICEQUERYREMOVEFAILED');
  break;
 case DBT_DEVICEREMOVEPENDING:
  Msg.Format('DBT_DEVICEREMOVEPENDING');
  break;
 case DBT_DEVICEREMOVECOMPLETE:
  Msg.Format('DBT_DEVICEREMOVECOMPLETE');
  break;
 case DBT_DEVICETYPESPECIFIC:
  Msg.Format('DBT_DEVICETYPESPECIFIC');
  break;
 case DBT_QUERYCHANGECONFIG:
  Msg.Format('DBT_QUERYCHANGECONFIG');
  break;
 case DBT_DEVNODES_CHANGED:
  Msg.Format('DBT_DEVNODES_CHANGED');
  break;
 case DBT_USERDEFINED:
  Msg.Format('DBT_USERDEFINED');
  break;
 default:
  Msg.Format('Event type %d',nEventType);
 }
 PDEV_BROADCAST_DEVICEINTERfACE pdbch = (PDEV_BROADCAST_DEVICEINTERFACE)dwData;
 if (pdbch!=NULL && pdbch->dbcc_devicetype==DBT_DEVTYP_DEVICEINTERFACE) {
  CString Msg2;
  Msg2.Format('%s: %s',Msg,pdbch->dbcc_name);
  Msg = Msg2;
 }
 CListBox* EventList = (CListBox*)GetDlgItem(IOC_EVENT_LIST);
 EventList->AddString(Msg);
 return TRUE; // or BROADCAST_QUERY_DENY to deny a query remove
}

Running Wdm2Notify in Windows 98

Figure 9.2 shows some typical output in the Wdm2Notify window in Windows 98 as the Wdm2 driver is updated for an installed Wdm2 device. First the PnP Manager asks if it is OK for the existing Wdm2 device to be removed. Then it issues remove pending and remove complete messages. When the driver has been updated, the Wdm2 device is added again resulting in a device arrival message. Finally, a DBT_DEVNODES_CHANGED event indicates that the device tree has changed.

I am not sure why there are so many duplicate device change messages.

If Wdm2Notify returns BROADCAST_QUERY_DENY to the Query Remove message, the remove is correctly refused and a DBT_DEVICEQUERYREMOVEFAILED message is then issued.

Figure 9.2 Wdm2Notify output in Windows 98

Running Wdm2Notify in Windows 2000

The Beta 2 version of Windows 2000 produces output very different from Wdm2Notify. It issues only a DBT_DEVICEREMOVECOMPLETE message and then a DBT_DEVICEARRIVAL message. A Query Remove request is not issued and there are no repeat messages. I hope that the final version of W2000 will issue more PnP Notification device change messages to Win32 applications.

Device Driver PnP Notification

A driver uses PnP Notification to find devices with a particular device interface. A driver does this so that it can issue calls to the devices that it finds. It may wish to layer its own device on top of each found device. This technique is commonly used when finding Human Input Devices, and a full example of this is given in Chapter 23.

PnP Notification in device drivers works in a similar way to Win32 applications. Remember that this is one device driver asking for device change notifications about devices controlled by another driver.

The driver must call IoRegisterPlugPlayNotification to indicate which events it is interested in receiving, and eventually call IoUnregisterPlugPlayNotification when done. You must pass the name of a callback routine to IoRegisterPlugPlayNotification, along with a context pointer.

In device drivers, you can ask for three different categories of PnP Notification events. If you ask for EventCategoryDeviceInterfaceChange events your callback routine is passed a DEVICE_INTERFACE_CHANGE_NOTIFICATION structure that notifies you only of device removal and device arrival events, along with the appropriate symbolic link. Specify the relevant GUID in the EventCategoryData parameter of IoRegisterPlugPlayNotification. If you specify PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES for the EventCategoryFlags parameter, arrival events are also sent straightaway for any existing devices that have a matching device interface GUID.

If you register for EventCategoryHardwareProfileChange events, you receive query change, change complete, and change cancelled events.

Finally, if you ask for EventCategoryTargetDeviceChange events, you receive query remove, removal completes, and remove cancelled messages for one specific device. You must supply a pointer to the relevant file object as the EventCategoryData parameter of IoRegisterPlugPlayNotification. I assume that you can reject query remove requests.

Driver PnP Notification is particularly important for client drivers that use device interfaces exposed by the system class drivers. For example, kernel mode Human Input Device (HID) client drivers can use PnP Notification to identify all installed HID devices. See Chapter 23 for a full example of PnP Notification in device drivers.

As mentioned earlier, device stacks cannot be changed once they are built. PnP Notification lets you find existing devices and effectively layer on top of them.

Notification Request Driver Interactions

As might expect, Win32 programs and device drivers that register for PnP Notification events will effect the operation of a driver. Query remove requests are processed by PnP Notification applications and drivers before the main driver receives an IRP_MN_QUERY_REMOVE_DEVICE IRP. Cancel remove notification messages are sent to applications and other drivers after the main driver has processed its IRP_MN_CANCEL_REMOVE_DEVICE message. Remove pending messages are sent before a device is removed (or surprise removed) and a remove complete notification message is sent afterwards.

Advanced Plug and Play

This section looks at some advanced Plug and Play topics.

Bus Drivers

This section looks briefly at the job a bus driver must do. Please consult the DDK documentation for full details. The W2000 DDK source code kernelserenum example shows how a bus driver is coded.

Bus drivers must manage their device objects carefully. A bus driver has a Functional Device Object (FDO) for each instance of a bus. A bus driver detects any devices on its bus and creates