chapter 5.2: UMDF对象模型的实现

UMDF基于COM，只用COM的query-interface和reference-counting机制，而不依赖COM的所有机制

类型：

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命名习惯
interface: IWDF[Object][[Description]]
    [Object]:导出interface的object
    [Description]: 指明操作于object的哪一部分
    例子：device导出了IWDFDevice接口，I/O target导出了IWDFIoTarget/IWDFIoTargetStateManagement接口
Method：[Action][Qualifier]
    [Action]: 动词，表示动作
    [Qualifier]: 动作的对象或数据
    例子：Interface IWDFDevice含有CreateIoQueue和ConfigureRequestDispatching方法
Property name:{Set|Get}[Data] 和 {Assign|Retrieve}[Data]
    [Data]：field
    例子：IWDFDevice::GetPnpState
event callback interface: I[Object]Callback[Description]
    [objcet]: 对象类型
    [Description]：做什么
    例子：IQueueCallbackWrite：callback对象实现的在写请求发生时的响应
        例外：IPnpCallbackXxx，不由Pnp对象实现，而由deivce object实现，响应Pnp事件
UMDF method within callback：On[Event]
    [event]：对应callback的事件
    例子：IQueueCallbackWrite::OnWrite


UMDF的framework object和Interface

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 fromIWDFObject.	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 fromIWDFObject.	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 fromIWDFObject.	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 fromIWDFFile.	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 fromIWDFObject.	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 fromIWDF-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 fromIWDFObject.	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 fromIWDFObject.	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 fromIWDFIoTarget.	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 fromIWDFRequestCompletionParams.	IWDFUsbRequestCompletionParams

UMDF Driver Callback Object和Interface
每个UMDF driver必须实现一个callback object，并对每个支持的Device实现一个callback object
driver对每个callback object必须实现IUnknown interface
    UMDF Echo, Skeleton和USB sample: Comsup.h中在CUnknown class中实现了IUnknown
    ** 在自己的设备中，可以在driver class中包含Comsup.h，并把CUnknown作为基类


列出了driver可以实现的Callback interface

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 registerIDriverEntry 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.

UMDF例子：object和callback interfaces
Fx2_Driver sample实现的driver，图中没有表示IUnknown，以及支持I/O queue的对象和callback interfaces

图解释：framework driver object使用了driver callback object的IDriverEntry interface
driver callback object使用了framework driver object的IWDFDriver interface