Developing Drivers with the Windows Driver Foundation (Pro Developer)

 UMDF   UMDF is a COM-based programming model that supports the development of function and filter drivers for protocol-based Plug and Play devices, such as USB devices. The framework is a DLL that implements the WDF object model by providing in-process COM-based driver objects, device objects, I/O request objects, and so on. The driver is a DLL that consists of a collection of in-process COM-based callback objects that handle events raised by the associated framework objects.

COM was chosen as a basis for UMDF for several reasons:

• COM is already familiar to many programmers.

• COM interfaces enable logical groupings of functions, making the DDI easy to understand and navigate.

• Numerous tools, including ATL, support COM-based applications and objects.

Chapter 18, "An Introduction to COM," provides information about COM programming.

The UMDF programming model is based on the following two types of objects:

• Framework objects These objects belong to the framework and represent the driver itself, the device that the driver manages, I/O queues for managing I/O requests, and so on.

• Callback objects The driver implements these objects and registers them with UMDF. Each object provides device-specific responses to events raised by a framework object.

The UMDF DDI-which includes both the objects that the framework provides and the callback objects that the driver implements-is exposed entirely through COM interfaces. Drivers use an interface pointer, rather than an object pointer, to interact with a framework object. Framework objects, in turn, interact with driver-implemented callback objects through the appropriate interface.

UMDF Framework Objects

With UMDF, framework objects are created in the following ways:

• The framework creates the object.

  For example, when the framework loads a driver, it creates a framework driver object and passes a pointer to the driver object's IWDFDriver and IWDFDeviceInitialize interfaces to the driver callback object.

• The driver creates the object.

  For example, the driver creates a framework device object by calling IWDFDriver:: CreateDevice.

• Some objects, such as I/O request objects, can be created by either the framework or the driver, depending on circumstances.

The interfaces that framework objects expose are named IWDFObject, where Object refers to the object that exports the interface. In addition to IUnknown, all framework objects expose one or more interfaces that provide access to the object's functionality. For example, the framework device object also exports IWDFDevice and IWDFObject. Each interface contains one or more methods that serve the following purposes:

• Methods instruct the object to perform an action.

• Properties provide access to data.

  Generally each property consists of two methods; one method is called to read the existing data value and the other method is called to write a new value. Properties that do not allow both read and write access to the data have only a single method. The different types are distinguished by naming conventions.

Chapter 5, "WDF Object Model," describes the UMDF naming conventions.

UMDF Callback Objects

The framework provides default handling for all events. Drivers can override the framework's default event handling by implementing callback objects to handle events of interest and by registering the objects with the framework. Callback objects expose one or more callback interfaces, each of which handles a set of related events. Callback interfaces consist of one or more methods-one for each event-that the framework calls to notify the driver of an event and to pass the callback object any related data.

Drivers register callback objects by passing a pointer to one of the object's interfaces to the framework object that raises the related event. Drivers register callback objects in one of two ways, depending on whether the driver or the framework creates the framework object:

• Driver-Created Framework Objects The driver typically registers callback objects when it calls the framework method that creates the framework object. For example, a driver registers its device callback object when the driver calls IWDFDriver::CreateDevice to create the framework device object.

• Framework-Created Framework Objects Objects that are created by the framework typically expose one or more methods that the driver can call to register a callback object for a particular event. For example, to register a request-completion callback object for an I/O request, the driver calls the I/O request object's IWDFIoRequest::SetCompletionCallback method.

The events that a driver chooses to handle determine which interfaces each callback object exposes. For example, if a driver must handle a queue object's read event but not its cleanup event, the callback object would expose a single callback interface- IQueueCallbackRead. To handle both the read and cleanup events, the callback object would expose IQueueCallbackRead and IObjectCleanup. Sometimes a framework object does not raise any interesting events, so a callback object is unnecessary. For example, drivers often are not required to handle the events that memory objects raise.

 Note  Callback objects are not necessarily restricted to handling the events that a single framework object raises. For example, the Fx2_Driver sample's device callback object exposes three callback interfaces: IPnpCallbackHardware, IPnpCallback, and IRequestCallbackRequestCompletion. The first two are registered with the framework device object to handle Plug and Play and power management events. IRequestCallbackRequestCompletion is registered with a framework queue object to handle request completion.