5. Sample Software-Only Driver
The Featured Toaster sample extends the Simple Toaster sample by adding support for the following features:
File create and close requests.
Additional device object attributes.
Plug and Play and power management events.
Windows management instrumentation (WMI).
This sample is supplied in Toaster\Func\Featured and supports the same features as the Featured2 Toaster sample for WDM, which is provided in the WDK.
5.1. File Create and Close Requests
File object events occur when applications and
kernel-mode components that open a handle to the device issue create,
close, and cleanup requests on the device. Drivers that handle such
requests must configure the device object with the appropriate
callbacks.
To handle create events, a driver can either receive
the events from a queue or can supply an event callback that is invoked
immediately. The driver’s options are the following:
To be called immediately, the driver supplies an EvtDeviceFileCreate callback and registers it from the EvtDriverDeviceAdd callback by calling WdfDeviceInitSetFileObjectConfig.
To configure a queue to receive the requests, the driver calls WdfDeviceConfigureRequestDispatching and specifies WdfRequestTypeCreate. If the queue is not manual, the driver must register an EvtIoDefault callback, which is called when a create request arrives.
Queuing takes precedence over the EvtDeviceFileCreate callback—that is, if the driver both registers for EvtDeviceFileCreate
events and configures a queue to receive such requests, KMDF queues the
requests and does not invoke the callback. KMDF does not queue requests
to a default queue; the driver must explicitly configure a queue to
receive them.
In a function or bus driver, if a create request arrives for which the driver has neither registered an EvtDeviceFileCreate
callback function nor configured a queue to receive create request,
KMDF opens a file object to represent the device and completes the
request with STATUS_SUCCESS.
Therefore, any function or bus driver that does not accept create or
open requests from user-mode applications—and thus does not register a
device interface—must register an EvtDeviceFileCreate
callback that explicitly fails such requests. Supplying a callback to
fail create requests ensures that a rogue user-mode application cannot
gain access to the device.
If a filter driver does not handle create requests,
KMDF by default forwards all create, cleanup, and close requests to the
default I/O target (the next lower driver).
Filter drivers that handle create requests should
perform whatever filtering tasks are required and then forward such
requests to the default I/O target. If the filter driver completes a
create request for a file object, it should set AutoForwardCleanupClose to WdfFalse
in the file object configuration so that KMDF completes cleanup and
close requests for the file object instead of forwarding them.
To handle file close and cleanup requests on a device handle, the driver supplies the EvtFileClose and EvtFileCleanup callbacks. It registers both of these callbacks in its EvtDriverDeviceAdd function.
5. 1.1. Register EvtDeviceFileCreate and EvtFileClose Callbacks
The following code is excerpted from the Featured Toaster’s ToasterEvtDeviceAdd function. It shows how the driver registers the EvtDeviceFileCreate and EvtFileClose callbacks.
WDF_FILEOBJECT_CONFIG_INIT(
&fileConfig,
ToasterEvtDeviceFileCreate,
ToasterEvtFileClose,
WDF_NO_EVENT_CALLBACK // not interested in Cleanup
);
WdfDeviceInitSetFileObjectConfig(DeviceInit,
&fileConfig,
WDF_NO_OBJECT_ATTRIBUTES);
As the example shows, the driver initializes a WDF_FILEOBJECT_CONFIG structure by calling the configuration function and supplying pointers to its EvtDeviceFileCreate and EvtFileClose callbacks. The driver does not implement the EvtFileCleanup callback, so it supplies WDF_NO_EVENT_CALLBACK instead of a third function pointer.
It then calls WdfDeviceInitSetFileObjectConfig to record these settings in the WDFDEVICE_INIT structure (DeviceInit), which the framework uses later when it creates the device object.
The EvtDeviceFileCreate and EvtFileClose functions are stubs in the Featured Toaster driver, so they are not shown here.
