Information Technology Fundamentals – Working With Device Interfaces

Working with Device Interfaces

A device interface is a symbolic link that an application uses to access a Plug and Play (PnP) device. A user-mode application is able to pass the symbolic link name of an interface to an API element, such as the Microsoft Win32 CreateFile method. To retrieve the symbolic link name of a device interface, the user-mode application may utilise configuration manager or SetupApi routines. Refer to Enumerating installed device interfaces for additional details.

Each device interface is a member of a class of device interfaces. A driver stack for a CD-ROM device, for instance, may provide an interface that is a member of the GUID DEVINTERFACE CDROM class. One of the CD-ROM device's drivers would register an instance of the GUID DEVINTERFACE CDROM class to notify the operating system and programmes that a CD-ROM device is present. 

Registering an Interface Device

A framework-based driver can call WdfDeviceCreateDeviceInterface from within its EvtDriverDeviceAdd callback method to register an instance of a device interface class. If the driver supports multiple instances of the interface, it can assign each instance with a unique reference string.

After registering a device interface, the driver can call WdfDeviceRetrieveDeviceInterfaceString to retrieve the symbolic link name that the operating system has allocated to the device interface.

Activating and Deactivating a Device Interface

After a driver runs WdfDeviceCreateDeviceInterface from EVT_WDF_DRIVER_DEVICE_ADD, the framework automatically enables and disables a device's interfaces during PnP enumeration and removal, respectively.

Note that device power status changes and PnP resource rebalancing do not affect the state of the interface. Calling WdfDeviceSetDeviceInterfaceStateEx with the EnableInterface option set to FALSE will prevent the interface from being automatically enabled during PnP startup.

Interfaces built after the device has already begun will not be enabled automatically. To enable such interfaces, the driver must execute WdfDeviceSetDeviceInterfaceState or WdfDeviceSetDeviceInterfaceStateEx.

If necessary, a driver can disable and re-enable a device interface. If a driver detects that its device has stopped responding, it can call WdfDeviceSetDeviceInterfaceState or WdfDeviceSetDeviceInterfaceStateEx to disable the device's interfaces and prevent applications from getting new handles to the interface. (Existing interface handles are not changed.) If the device later becomes accessible, the driver can reenable the interfaces by calling WdfDeviceSetDeviceInterfaceState or WdfDeviceSetDeviceInterfaceStateEx.

Receiving Device Interface Access Requests

The framework invokes the driver's EvtDeviceFileCreate callback method when an application or kernel-mode component requests access to a driver's device interface. The driver may invoke WdfFileObjectGetFileName to acquire the name of the device or file being accessed by the application or kernel-mode component. If the driver registered the device interface with a reference string, the operating system includes the reference string in the file or device name returned by WdfFileObjectGetFileName.

Accessing the Device Interface of Another Driver

This section demonstrates how a Kernel-Mode Driver Framework (KMDF) driver or a User-Mode Driver Framework (UMDF) version 2 driver registers for notification of arrival or removal of a device interface provided by another driver, followed by the creation of a remote I/O target to communicate with the device represented by the device interface.

A KMDF driver calls IoRegisterPlugPlayNotification to register for notice of device interface events, while a UMDF 2 driver calls CM Register Notification. In both circumstances, the driver's EvtDriverDeviceAdd callback method will invoke the appropriate code.

Registering a device interface class

Two methods exist for registering a device interface class:

• A driver that controls a PnP device can register a device interface with a specific device interface class. In conjunction with registering the device interface, the device interface class will be produced automatically. This subject discusses how to register a device interface using the associated functions. 
• An INF file can contain INF DDInstall.Interface sections.

A WDM driver's device objects are unnamed. When calling IoCreateDevice to construct a device object, the driver should instead give a null string for the device name. Create a device object for further details.

After constructing the device object and adding it to the device stack, a driver runs IoRegisterDeviceInterface to register a device interface class and generate an instance of the class's device interface. Typically, the function driver performs this call from its AddDevice procedure, but occasionally the interface is registered by a filter driver.

The procedure retrieves the name of a symbolic link. When enabling or disabling a device interface instance, a driver transmits the link name. Before the driver enables a device interface instance, other system components cannot utilise it. Details are available at Enabling and deactivating a device interface instance.

The driver also uses the symbolic link name to access the registry key where it can store device interface-specific information. The link name is used by applications to access the device.

A driver may invoke IoRegisterDeviceInterface as frequently as required to register instances of additional device interface classes.