Writing Windows WDM Device Drivers

This section briefly describes the Plug and Plug minor function code IRPs that have not been described in full before. These IRPs are handled by PnP bus drivers. The notes for each function code indicate if it is possible for a function driver to intercept the IRP.

Most function drivers ignore all these PnP IRPs. However, a function driver that performs Power Management may well want to handle IRP_MN_QUERY_CAPABILITIES. The following chapter describes how this is done.

IRP_MN_DEVICE_USAGE_NOTIFICATION

This message tells a driver if its device is in the path of a paging, hibernation, or crash dump file. Do not allow a device to be removed until you are notified that no critical file is on its path.

IRP_MN_FILTER_RESOURCE_REQUIREMENTS

The Windows 2000 PnP Manager sends this IRP to a device stack so filter and function drivers can adjust the resources required by the device, if appropriate. Function, filter, and bus drivers can handle this request.

IRP_MN_QUERY_BUS_INFORMATION

The PnP Manager uses this IRP to request the type and instance number of a device's parent bus.

Bus drivers should handle this request for their child devices (PDOs). Function and filter drivers do not handle this IRP.

IRP_MN_QUERY_CAPABILITIES

The PnP Manager sends this IRP to get the capabilities of a device, such as whether the device can be locked or ejected, and various Power Management features. Function and filter drivers can handle this request if they alter the capabilities supported by the bus driver. Bus drivers must handle this request for their child devices.

This IRP is sent twice, both before and after function drivers are loaded and started.

A driver can send one of these IRPs down the stack to see what the bus driver capabilities are.

IRP_MN_QUERY_DEVICE_RELATIONS

This IRP asks how this device relates to other devices and comes in five different forms. All forms return an array of pointers to the relevant PDOs.

A BusRelations query asks for the PDOs of all the devices physically present on the bus. EjectionRelations asks which devices are also ejected if this device is ejected. PowerRelations asks which devices are also powered down when this device is powered down. RemovalRelations asks which devices must be removed when this device is removed. TargetDeviceRelation calls ObReferenceObject for the device PDO and returns the PDO.

IRP_MN_QUERY_DEVICE_TEXT

The PnP Manager uses this IRP to get a device's description or location information. Bus drivers must handle this request for their child devices if the bus supports this information. Function and filter drivers do not handle this IRP.

Parameters.QueryDeviceText.DeviceTextType is either DeviceTextDescription or DeviceTextLocationInformation.Parameters.QueryDeviceText.LocaleId is an LCID specifying the locale for the requested text.

IRP_MN_QUERY_ID

This IRP gets device, hardware, compatible, or instance IDs for a device, depending on whether Parameters.QueryId.IdType is BusQueryDeviceID, BusQueryHardwareIDs, BusQueryCompatibleIDs, or BusQueryInstanceID.

IRP_MN_QUERY_INTERFACE

The IRP_MN_QUERY_INTERFACE request enables a driver to export a direct-call interface to other drivers.

IRP_MN_QUERY_PNP_DEVICE_STATE

The query asks the drivers in the device stack to set any of the state bits shown in Table 9.3. Be careful not to overwrite any bits that are set by other drivers.

Table 9.3 Query device state bits

PNP_DEVICE_DISABLED	The device is physically present but is disabled in hardware.
PNP_DEVICE_DONT_DISPLAY_IN_UI	Don't display the device in the user interface. The device is physically present but not usable in the current configuration.
PNP_DEVICE_FAILED	The device is present but not functioning correctly. When both this flag and PNP_DEVICE_RESOURCE_REQUIREMENTS_CHANGED are set, the device must be stopped before the PnP Manager assigns new hardware resources.
PNP_DEVICE_REMOVED	The device has been physically removed.
PNP_DEVICE_RESOURCE_REQUIREMENTS_CHANGED	The resource requirements for the device have changed.
PNP_DEVICE_NOT_DISABLEABLE	The device cannot be disabled.

If any of the state characteristics change after the initial query, a driver notifies the PnP Manager by calling IoInvalidateDeviceState. In response to a call to IoInvalidateDeviceState, the PnP Manager queries the device's PNP_DEVICE_STATE again.

IRP_MN_QUERY_RESOURCE_REQUIREMENTS

The PnP Manager uses this IRP to get a device's resource requirements list. Bus drivers must handle this request for their child devices that require hardware resources. Function and filter drivers do not handle this IRP.

IRP_MN_QUERY_RESOURCES

The PnP Manager uses this IRP to get a device's boot configuration resources. Bus drivers must handle this request for their child devices that require hardware resources. Function and filter drivers do not handle this IRP.

IRP_MN_READ_CONFIG

Bus drivers for buses with configuration space must return the relevant information for their child devices. Filter and function drivers do not handle this request.

IRP_MN_SET_LOCK

This request is used to lock or unlock a device. Bus drivers must handle this IRP for a child device that supports device locking. Function and filter drivers do not handle this request.

IRP_MN_WRITE_CONFIG

Bus drivers must write the given information into the configuration space of the child device. Function and filter drivers do not handle this request.

Plug and Play Notification

Plug and Play Notification informs Win32 programs and device drivers of device change events that interest them, such as device arrival and removal. They can also refuse requests to remove a device. PnP Notification uses a device interface GUID or a file handle to identify which devices are of interest.

Win32 applications and device drivers register to receive PnP notifications so that they can cope if a device is about to be removed, or if they want to use a device that has just been added. For example, if a program is in the middle of a long transfer, it could refuse permission for a device to be removed. In addition, device drivers can be informed of all devices that expose the required device interface.

Win32 PnP Notification

A Win32 program calls RegisterDeviceNotification to register that it wants to receive PnP Notification device change messages. You must pass either a window handle or (in W2000 only) a service status handle. The NotificationFilter parameter points a structure that says what type of events you want to receive.

To receive events about devices with a particular device interface, pass a DEV_BROADCAST_DEVICEINTERFACE structure pointer to RegisterDeviceNotification. Set the dbcc_classguid field to the device interface GUID of interest. Set the dbcc_size and dbcc_devicetype fields appropriately.

I have not tried it, but passing a DEV_BROADCAST_HANDLE structure pointer should let you receive events from one open file handle, including custom events.

Do not forget to call UnregisterDeviceNotification when you do not wish to receive any further PnP Notification events.

Device Change Message

Each PnP Notification event is sent to a Win32 program as a WM_DEVICECHANGE message. In MFC applications, this appears in an OnDeviceChange handler.