UMDF Object Model Implementation

In UMDF, the framework maintains a set of framework objects, and the driver creates a callback object that corresponds to each framework object for which the driver requires an event callback. The callback objects expose callback interfaces that are defined by the framework.

UMDF drivers use the following types of objects:

Driver-created file	I/O completion parameters
Base object	I/O target
Driver	Memory
Device	USB device
File	USB I/O target
I/O request	USB interface
I/O queue

UMDF objects and interfaces are based on the COM programming pattern. UMDF uses only the query-interface and reference-counting features of COM; it does not depend on the entire COM infrastructure and runtime library.

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

UMDF Naming Conventions

UMDF follows naming conventions for the interfaces that it implements and the callback interfaces that it defines.

 UMDF interface names  The UMDF-implemented interfaces are named:

• IWDFObject[Description]

where:

• Object specifies the UMDF object that exposes the interface.

• Description is additional information that indicates which aspect of the object it acts on.

For example, framework device objects expose the IWDFDevice interface, which supports methods that manipulate a framework device object. Framework I/O target objects expose the IWDFIoTarget and IWDFIoTargetStateManagement interfaces.

 UMDF method names  Methods in UMDF interfaces are named:

• ActionQualifier

where:

• Action is a verb that indicates the action that the function performs.

• Qualifier specifies the object or data that is the target of the action.

For example, the IWDFDevice interface includes the CreateIoQueue and ConfigureRequestDispatching methods.

 UMDF property names  UMDF properties are named:

• {Set|Get}Data

• {Assign|Retrieve}Data

where:

• Data specifies the field that the function reads or writes.

Some properties can be read and written without failure, but other properties can sometimes fail. Functions with Set and Get in their names read and write properties without failure. Functions with Assign and Retrieve in their names can fail and return an HRESULT that contains a status value.

For example, IWDFDevice::GetPnpState and IWDFDevice::SetPnpState set and return the value of individual Plug and Play characteristics for a device object.

 UMDF event callback interface names  Event callback interfaces for UMDF objects are generally named:

• IObjectCallbackDescription

where:

• Object identifies the object type.

• Description indicates what the interface does.

For example, the IQueueCallbackWrite interface is implemented on a queue callback object. It supports a method that the framework calls in response to a write request.

The IPnpCallbackXxx interfaces are an exception. Although these interfaces have Pnp in their names, they are implemented on device objects. They support methods that respond to Plug and Play events.

UMDF methods within the callback interfaces are named:

• OnEvent

where:

• Event indicates the event for which the framework invokes the callback method.

For example, the framework calls the IQueueCallbackWrite::OnWrite method when a write request arrives for the device object. The IPnpCallback::OnD0Entry method is called when the device enters the working power state.

UMDF Framework Objects and Interfaces

Table 5-1 lists the interfaces that the framework implements on each type of object.

Table 5-1: UMDF Framework Objects and Interfaces
Open table as spreadsheet

Type of object	Object description	Interfaces	Interface description
Base object	Represents a generic base object for the driver to use as required.	IWDFObject	Supports actions common to all objects, such as locking, deletion, and managing the context area.
Device	Represents a device object. A driver typically has one device object for each device that it controls. Inherits from IWDFObject.	IWDFDevice	Provides device-specific information and creates device-specific objects.
		IWDFFileHandleTargetFactory	Creates an I/O target object based on a file handle.
		IWDFUsbTargetFactory	Creates a USB I/O target device object.
Driver	Represents the driver object itself. Every driver has one driver object. Inherits from IWDFObject.	IWDFDriver	Creates driver child objects and provides version information.
File	Represents a framework file object that was opened by the CreateFile function, through which applications can access the device. Inherits from IWDFObject.	IWDFFile	Returns information about the file and device that are associated with a file handle.
Driver-created file	Represents a framework file object that the driver created. Inherits from IWDFFile.	IWDFDriverCreatedFile	Closes a driver-created file.
I/O queue	Represents an I/O queue, which controls the flow of I/O in the driver. A driver can have any number of I/O queues. Inherits from IWDFObject.	IWDFIoQueue	Configures, manages, and retrieves requests and information from a queue.
I/O request	Represents a request for device I/O. Inherits from IWDFObject.	IWDFIoRequest	Formats, sends, cancels, and returns information about an I/O request.
I/O request completion information	Represents the completion information for an I/O request.	IWDFRequestCompletionParams	Returns status, number of bytes, and request type for a completed I/O request.
I/O request completion parameters	Exposes the parameters returned in a completed I/O request. Inherits from IWDF-RequestCompletionParams.	IWDFIoRequestCompletionParams	Returns buffers for read, write, and device I/O control requests.
I/O target	Represents the next-lower driver in the device stack, to which the driver sends I/O requests. Inherits from IWDFObject.	IWDFIoTarget	Formats and cancels I/O requests and returns information about the target file.
		IWDFIoTargetStateManagement	Monitors and controls the state of an I/O target.
Memory	Represents memory that the driver uses, typically an input or output buffer that is associated with an I/O request. Inherits from IWDFObject.	IWDFMemory	Copies data to and from a memory buffer and returns information about the buffer.
Property store	Represents an object through which a driver can maintain persistent data in the registry between driver loads and unloads.	IWDFNamedPropertyStore	Enables a driver to query and set information in the registry.
USB interface	Represents an interface on a USB device. Inherits from IWDFObject.	IWDFUsbInterface	Returns information about and selects a setting for a USB interface.
USB target device	Represents a USB device object that is an I/O target. Inherits from IWDFIoTarget.	IWDFUsbTargetDevice	Formats requests for and returns information about a USB target device.
USB target pipe	Represents a USB pipe that is an I/O target. Inherits from IWDFIoTarget.	IWDFUsbTargetPipe	Manages and returns information about a USB pipe.
USB I/O request completion parameters	Exposes the parameters returned in a completed I/O request to a USB target. Inherits from IWDFRequestCompletionParams.	IWDFUsbRequestCompletionParams	Returns request type and buffers for USB read, write, and device I/O control requests.

UMDF Driver Callback Objects and Interfaces

A UMDF driver assigns a callback object to each framework object whose events the driver is interested in and implements callback interfaces for those events on the callback object. Every UMDF driver must implement one driver callback object for the driver itself and one device callback object for each device that it supports. Most drivers also implement a queue callback object for each queue.

The driver must implement the IUnknown interface for each callback object. The driver can do this in any of several ways. The UMDF Echo, Skeleton, and USB samples include the Comsup.h header file, which implements IUnknown in the CUnknown base class. In your own driver, you can include Comsup.h and list CUnknown as a base class when you declare the driver's classes.

Chapter 13, "UMDF Driver Template," provides details about how to use the Skeleton sample as a template for your own driver development.

Table 5-2 lists the possible callback interfaces that a driver can implement.

Table 5-2: UMDF Driver Callback Objects and Interfaces
Open table as spreadsheet

Type of object	Callback interfaces	Description of interface
All objects	IObjectCleanup	Provides processing that is required before an object is disposed, typically releasing any circular references.
Driver	IDriverEntry	Provides the main entry point from the framework into the driver and methods to initialize the driver and add its devices. This object is required for all drivers. Unlike other callback interfaces, the driver does not register IDriverEntry with any particular object. Instead, the framework requests this interface from the driver's CoClass object when it loads the driver.
Device	IPnpCallback	Handles device stop, removal, and power state changes.
	IPnpCallbackHardware	Provides hardware-related operations before device power-up and after device power-down.
	IPnpCallbackSelfManagedIo	Enables the driver to perform actions when the framework starts and stops I/O processing at specific Plug and Play and power management state transitions.
File	IFileCallbackCleanup	Handles cleanup requests for file objects on a specific device, typically so that the driver can cancel any outstanding I/O requests for the file before it is closed.
	IFileCallbackClose	Receives close notifications for file objects on a specific device so that the driver can release file-specific resources.
I/O queue	IQueueCallbackCreate	Handles file create requests.
	IQueueCallbackDefaultIoHandler	Handles create, device I/O control, read, and write requests for which no other interface has been implemented.
	IQueueCallbackDeviceIoControl	Handles device I/O control requests.
	IQueueCallbackIoResume	Resumes processing an I/O request after its queue has been stopped.
	IQueueCallbackIoStop	Stops processing an I/O request because its queue is stopping.
	IQueueCallbackStateChange	Notifies the driver when the state of a queue changes.
	IQueueCallbackRead	Handles read requests.
	IQueueCallbackWrite	Handles write requests.
I/O request	IImpersonateCallback	Performs tasks while the driver impersonates the client that issued the I/O request.
	IRequestCallbackCancel	Performs tasks after an I/O request is canceled.
	IRequestCallbackRequestCompletion	Performs tasks when an I/O request is completed.

When an event occurs, the framework calls methods on the appropriate callback interfaces so that the driver can respond to the events that are associated with the request. For example, if the driver has configured a queue for read requests, the framework calls methods in the queue callback object's IQueueCallbackRead interface when it receives such a request.

Tip 

Framework objects and callback objects are not required to correspond on a one-to-one basis. The driver can do whatever makes the most sense for the callback and the driver.

For example, consider I/O cancellation and completion callbacks. You can implement these interfaces on whichever callback object seems most appropriate. If your driver has a queue that also manages continuous reads on an interrupt pipe, then it might make sense to implement the cancellation and completion callback interfaces on the queue. Likewise, if your driver allocates a context area for each request to track the state of the request, then you could create a callback object instead and implement the I/O cancellation and completion callback interfaces on the callback object.

UMDF Example: Objects and Callback Interfaces

Figure 5-1 shows the primary callback interfaces that the Fx2_Driver sample implements for the driver and device objects. IUnknown-which all COM objects must support-is not shown, nor are the objects and callback interfaces that support the driver's I/O queues.

Figure 5-1: Driver and device callback objects in the Fx2_Driver sample

As the figure shows, the framework implements a driver object and a device object, and the Fx2_Driver sample creates a driver callback object and a device callback object. The framework driver object uses the driver callback object's IDriverEntry interface, and the driver callback object, in turn, uses the IWDFDriver interface on the framework driver object.

The framework device object exposes the IWDFDevice and IWDFDeviceInitialize interfaces, which the device callback object uses. The device callback object also implements the IPnpCallbackHardware and IPnpCallback interfaces, which the framework device object uses.