Using COM to Develop UMDF Drivers : Basic Infrastructure Implementation

A dynamic-link library (DLL) can contain any number of in-process COM objects, but it must have a single entry point that is named DllMain. Windows calls DllMain after the driver binary has been loaded into a host process and before it is unloaded. The function is also called when threads are created or destroyed. The dwReason parameter indicates why the function was called.

When a UMDF driver’s DllMain function is called for DLL loading or unloading, it should perform only simple module-wide initialization and termination tasks, such as initializing or freeing global variables and registering or unregistering Window Software Trace Preprocessor (WPP) tracing. There is a number of things DllMain should definitely not do, such as calling LoadLibrary.

When a UMDF driver’s DllMain function is called for thread creation or destruction, it can ignore the call. For more information, see the function’s reference page in the Platform Software Developers Kit (SDK). For a typical DllMain implementation, see the dllsup.cpp from the UMDF sample code.

2. DllGetClassObject

Because class factories aren’t exported by name, there is no direct way for a client to get access to them. Instead, the DLL exports the DllGetClassObject function by name, which allows it to be called by any client with access to the DLL. For many COM DLLs, including the UMDF samples, DllGetClassObject is the only function that is listed in the project’s .def file to be exported by name from the DLL.

When a client wants to create an instance of one of the COM objects in the DLL, it passes the CLSID of the desired class factory object to DllGetClassObject and the IID of the desired interface, usually IClassFactory. DllGetClassObject creates a new class factory object and returns a pointer to the appropriate interface on the object. The client can then use the IClassFactory::CreateInstance method to create an instance of the object. For a typical implementation of DllGetClassObject, see dllsup.cpp from the UMDF’s sample code in the book.

A standard COM server is also required to implement DllCanUnloadNow and, optionally, DllRegisterServer and DllUnregisterServer. These exports are not required for UMDF drivers.

3. Driver Object’s Class Factory

Some COM objects must be created by external clients. For UMDF drivers, there is usually only one such object: that is the driver callback object. A COM object that can be created by an external client must have a class factory. This is a small specialized COM object whose sole purpose is to create a new instance of its associated COM object and return a pointer to a specified interface. For a typical implementation of a class factory, see comsup.cpp from the UMDF’s sample code.

Class factories usually expose only one interface in addition to IUnknown, IClassFactory. The IClassFactory interface has two members:

• CreateInstance creates an instance of the object and returns the requested interface pointer to the client.

• LockServer can be used to keep the DLL in memory. UMDF class factories typically have only a token implementation because UMDF does not use LockServer.

Some recommendations for implementing CreateInstance are as follows.

• Ignore the first parameter. Its purpose is to support COM aggregation, which is not used by UMDF.

• Create a new driver callback object by whatever means is convenient. The sample code puts the object creation code in a static method on the class that implements the callback object.

• Return the appropriate interface as an OUT parameter. At this point, the object should have a reference count of 1.

4. Implementing a UMDF Callback Object

A UMDF driver consists of a collection of COM callback objects. These objects respond to notification by the UMDF run time and allow the driver to process various events, such as read or write requests. All callback objects are in-process COM objects. This means that they are packaged in a DLL and run in the process context of a UMDF host.

The basic requirements for implementing UMDF callback objects are relatively simple and straightforward:

• Implement the IUnknown methods to handle reference counting and provide pointers to the object’s interfaces.

• Implement the methods of the UMDF callback interfaces that are to be exported by the object.

4.1. Implementing the UMDF Callback Class

UMDF callback objects are typically implemented as a C++ class that contains the code to support IUnknown plus any UMDF interfaces that the object exposes. The UMDF interfaces are declared in wudfdd.h. Following are some of the requirements:

• The class must inherit from every interface that it exposes. However, it can do so indirectly, for example, by inheriting from a class that in turn inherits from one or more interfaces.

• Interfaces are declared as abstract base classes, so the class must implement all the interface methods.

• The class often inherits from a parent class in addition to interfaces. Many of the UMDF samples, for instance, inherit from a parent class, named CUnknown, that contains a base implementation of IUnknown.

• The class can contain private data members, public methods that are not part of an interface, and so on. These are for internal use and are not visible to clients.

• Constructors are optional. However, if a class has a constructor, it should contain no code in it that might fail. Put any code that can fail in a public initialization method that can be called after object creation.

As we mentioned, a UMDF callback object is typically implemented as a class that inherits from IUnknown and one or more object-specific interfaces. Listing 1 shows the full declaration of the CMyDriver class. The class inherits from a single UMDF interface IDriverEntry and inherits from IUnknown through the CUnknown parent class. For convenience, several of the simpler methods are implemented here, rather than in the associated .cpp file.

Listing 1. Declaration of a Driver’s Callback Object

Class CMyDriver : public Unknown, Public IDriveEntry
{
private:
   IDriverEntry * QueryIDriverEntry (VOID)
   {
      AddRef();
      return static_cast<IDriverEntry*>(this);
   }
   HRESULT initialize(VOID);
public:
   static HRESULT CreateInstance(__out PCMyDriver *Driver);
public:
   virtual HRESULT STDMETHODCALLTYPE OnInitialize(__in
          IWDFDriver *FxWdfDriver)
   {
      UNREFERENCED_PARAMETER (FxWdfDriver);
      return S_OK;
   }
   virtual HRESULT STDMETHODCALLTYPE OnDeviceAdd(
         __in IWDFDriver *FwWdfDriver,
         __in IWDFDeviceInitialize *FxDeviceInit);
   virtual VOID STDMETHODCALLTYPE OnDeinitialize(
         __in IWDFDriver *FxWdfDriver
         )
   {
      UNREFERENCED PARAMETER(FxWdfDriver);
      return;
   }
   virtual  ULONG STDMETHODCALLTYPE AddRef (VOID)
   {
      return __super::AddRef();
   }
   virtual ULONG STDMETHODCALLTYPE Release(VOID)
   {
      return __super::Release();
   }
   virtual HRESULT STDMETHODCALLTYPE QueryInterface(
      __in REFID InterfacedId,
      __deref_out PVOID *Object
      );
};

					  

IUnknown is the core COM interface; it is exposed by every COM object and is essential to the object’s operation. The approach that is used by the UMDF sample code is to have an IUnknown base class, called CUnknown, plus an implementation for each exposed interface that inherits from the base class.

4.2. Implementing AddRef and Release

Reference counting is arguably the key task of IUnknown. Normally, a single reference count is maintained for the object as a whole. The following are some recommendations for handling AddRef and Release:

• Have the interface-specific implementations pass their calls to the base implementation and let it handle incrementing or decrementing the reference count for the object.

• Use InterlockedIncrement and InterlockedDecrement to modify the reference count. This eliminates the possibility of a race condition.

• After the Release method decrements the reference count, check to see whether the count has gone to zero. If so, there are no outstanding interface pointers and you can use delete to destroy the object.

• Both AddRef and Release return the current reference count. Use this for debugging purposes.

5. Implementing QueryInterface

QueryInterface is the fundamental mechanism by which a COM object provides pointers to its interfaces. It responds to a client’s request by returning the specified interface pointer. The following are some recommendations for QueryInterface:

• QueryInterface must check the incoming IID to see if the request is for a supported interface. IsEquallD is a utility function declared in guiddef.h that simplifies comparing IIDs.

• If the object supports the requested interface, QueryInterface calls AddRef to increment the object’s reference count and returns the requested interface pointer. To return the pointer, QueryInterface casts a this pointer to the requested interface type. This cast is required because of the way in which C++ handles multiple inheritances.

• When a client queries for IUnknown, an object must always return the same IUnknown pointer regardless of which interface QueryInterface is called from.

The basic process of implementing UMDF callback interfaces is similar to IUnknown. Most of the implementation details are governed by the requirements of the individual methods.