Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Driver Callback Interfaces
The driver implements callback interfaces to provide device-specific responses to events. Each callback interface is implemented on a specific object type. For example, Plug and Play callback interfaces (IPnpCallback, IPnpCallbackHardware, IPnpCallbackSelfMangedIo) are implemented for device objects, and I/IO queue callback interfaces (IQueueCallbackCreate, IQueueCallbackRead, and so forth) are implemented on I/O queue objects.
When a Plug and Play, power management, or I/O request arrives, UMDF calls methods in the driver’s callback interfaces to handle the associated events. For example, when UMDF receives a read request, it calls methods in the driver’s IQueueCallbackRead interface.
A device implements callback interfaces only for the events that are important to its operation. When the event occurs for an object, the framework invokes the callback for that object. For example, the unexpected removal of a device is a Plug and Play event.
If a device can be removed unexpectedly, its driver should implement the IPnpCallback interface (which includes the OnSurpriseRemoval method) to perform device-specific operations upon ejection. When the Plug and Play manager sends a surprise-removal notification for the device, UMDF calls the OnSurpriseRemoval method with a pointer to the IWDFDevice interface for the device that has been removed.
For most events, a driver can either provide a callback interface or allow UMDF to perform a default action in response. For a few events, however, a driver-specific callback is required. For example, adding a device is an event for which every Plug and Play driver must include a callback. The driver object’s IDriverEntry::OnDeviceAdd callback creates the device object.
The names of the driver-implemented callback interfaces are generally in the form IObjectAction, where Object identifies the object to which the interface applies and Action indicates what the interface does. For example, the IQueueCallBackRead interface is implemented for I/O queues and contains methods called when a queue receives a read request.
The following table lists the possible callback interfaces a driver might implement.
Type of Object Callback InterfacesDescription
|
Base object, or any object that inherits from the base object type |
IObjectCleanup |
Provides process that is required before an object is deleted, typically releasing any references held on the object. |
|
Driver |
IDriverEntry |
Provides main entry point and methods to initialize the driver and add its devices. |
|
Device |
IPnpCallback IPnpCallbackHardware IPnpCallbackSelfManagedIo IFileCallbackCleanup IFileCallbackClose |
Handles device stop, removal, and power state changes. Provides hardware-related operations before device power-up and after device power-down. Provides driver, rather than framework, control over I/O operations at specific Plug and Play and power management states. Handles clean-up requests for file objects on a specific device. Handles close requests for file objects on a specific device. |
|
I/O queue |
IQueueCallbackCreate IQueueCallbackDefaultIoHandler IQueueCallbackDeviceIoControl IQueueCallbackIoResume IQueueCallbackIoStop IQueueCallbackRead IQueueCallbackWrite |
Handles the file create requests. Handles create, device I/O control, read, and write requests for which no other interface has been implemented. Handles device I/O control requests. Resumes processing an I/O request after its queue has been stopped. Stops processing an I/O request its queue is stopping. Handles read requests. Handles write requests. |
|
I/O request |
IImpersonateCallback IRequestCallbackCancel IRequestCallbackRequestCompletion |
Provides impersonation for certain Win32 I/O operations. Handles cancellation of an I/O request. Handles completion of an I/O request. |
To round out the discussion, the following figure shows the path that an I/O request takes from an application to a UMDF driver.
)
Callers use the Win32 API to send I/O requests to devices that are managed by UMDF drivers, just as they do for any other device. The Win32 API calls the appropriate kernel mode I/O routine, and the Windows kernel I/O manger creates an I/O request packet (IRP) and sends this IRP to the driver at the top of the kernel mode device stack for the target device.
For a device that is managed by a UMDF driver, the reflector is the driver at the top of the kernel mode driver stack.