DllGetClassObject

HRESULT DllGetClassObject(clsid, iid, ppv)

This is not a function in the COM Library itself; rather, it is a function that is exported from .DLL servers.

In the case that a call to the COM API function CoGetClassObject results in the class object having to be loaded from a .DLL, CoGetClassObject uses the DllGetClassObject that must be exported from the .DLL in order to actually retrieve the class.

Argument	Type	Description
clsid	REFCLSID	The class of the class factory being requested.
iid	REFIID	The interface with which the caller wants to talk to the class factory. Most often this is IID_IClassFactory but is not restricted to it.
ppv	void **	The place in which to put the interface pointer.

Return Value	Meaning
S_OK	Success.
E_NOINTERFACE	The requested interface was not supported on the class object.
E_OUTOFMEMORY	Memory could not be allocated to service the request.
E_UNEXPECTED	An unknown error occurred.

Note that since DllGetClassObject is passed the CLSID, a single implementation of this function can handle any number of classes. That also means that a single in-process server can implement any number of classes. The implementation of DllGetClassObject only need create the proper class factory for the requested CLSID.

Most implementation of this function for a single class look very much like the implementation of IClassFactory::CreateInstance as illustrated in the code below:

HRESULT DllGetClassObject(REFCLSID clsid, REFIID iid, void **ppv) {
   CTextRenderFactory * pCF;
   HRESULT              hr=E_OUTOFMEMORY;

   if (!CLSID_TextRender!=clsid)
      return E_FAIL;
   pCF=new CTextRenderFactory();
   if (NULL==pCF)
      return E_OUTOFMEMORY;

   //This validates the requested interface and calls AddRef
   hr=pCF->QueryInterface(iid, ppv);
   if (FAILED(hr))
      delete pCF;
   else
      ppv=pCF;
    return hr;
    }

As is conventional with object implementations, including class factories, construction of the object sets the reference count to zero such that the initial QueryInterface creates the first actual reference count. Upon successful return from this function, the class factory will have a reference count of one which must be released by the caller (COM or the client, whoever gets the interface pointer).

The structure of a .DLL server with its object and class factory is illustrated in Figure 6-1 below. This figure also illustrates the sequence of calls and events that happen when the client executes the standard object creation sequence of CoGetClassObject and IClassFactory::CreateInstance.

Figure 6-1. Creation sequence of an object from a .DLL server. Function calls not in COM are from the Windows API.