Note:
The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index.

At the heart of OLE 2 is the "OLE Component Object Model", or COM. COM defines a standard for how cooperating objects communicate to one another. This includes the details of what an "object" looks like, including how methods are dispatched on an object. COM also defines a base class, from which all COM compatible classes are derived. This base class is IUnknown. Although the IUnknown interface is referred to as a C++ class, COM is not specific to any one language — it can be implemented in C, PASCAL, or any other language that can support the binary layout of a COM object.

OLE refers to all classes derived from IUnknown as "interfaces." This is an important distinction, since an "interface" such as IUnknown carries with it no implementation. It simply defines the protocol by which objects communicate, not the specifics of what those implementations do. This is reasonable for a system that allows for maximum flexibility. It is MFC's job to implement a default behavior for MFC/C++ programs.

To understand MFC's implementation of IUnknown you must first understand what this interface is. A simplified version of IUnknown is defined below:

	Copy Code
class IUnknown { public: virtual HRESULT QueryInterface(REFIID iid, void** ppvObj) = 0; virtual ULONG AddRef() = 0; virtual ULONG Release() = 0; };

Note:
Certain necessary calling convention details, such as __stdcall are left out for this illustration.

The AddRef and Release member functions control memory management of the object. COM uses a reference counting scheme to keep track of objects. An object is never referenced directly as you would in C++. Instead, COM objects are always referenced through a pointer. To release the object when the owner is done using it, the object's Release member is called (as opposed to using operator delete, as would be done for a traditional C++ object). The reference counting mechanism allows for multiple references to a single object to be managed. An implementation of AddRef and Release maintains a reference count on the object — the object is not deleted until its reference count reaches zero.

AddRef and Release are fairly straightforward from an implementation standpoint. Here is a trivial implementation:

	Copy Code
ULONG CMyObj::AddRef() { return ++m_dwRef; } ULONG CMyObj::Release() { if (--m_dwRef == 0) { delete this; return 0; } return m_dwRef; }

The QueryInterface member function is a little more interesting. It is not very interesting to have an object whose only member functions are AddRef and Release — it would be nice to tell the object to do more things than IUnknown provides. This is where QueryInterface is useful. It allows you to obtain a different "interface" on the same object. These interfaces are usually derived from IUnknown and add additional functionality by adding new member functions. COM interfaces never have member variables declared in the interface, and all member functions are declared as pure-virtual. For example,

	Copy Code
class IPrintInterface : public IUnknown { public: virtual void PrintObject() = 0; };

To get an IPrintInterface if you only have an IUnknown, call IUnknown::QueryInterface using the IID of the IPrintInterface. An IID is a 128-bit number that uniquely identifies the interface. There is an IID for each interface that either you or OLE define. If pUnk is a pointer to an IUnknown object, the code to retrieve an IPrintInterface from it might be:

	Copy Code
IPrintInterface* pPrint = NULL; if (pUnk->QueryInterface(IID_IPrintInterface, (void**)&pPrint) == NOERROR) { pPrint->PrintObject(); pPrint->Release(); // release pointer obtained via QueryInterface }

That seems fairly easy, but how would you implement an object supporting both the IPrintInterface and IUnknown interface? In this case it is simple since the IPrintInterface is derived directly from IUnknown — by implementing IPrintInterface, IUnknown is automatically supported. For example:

	Copy Code
class CPrintObj : public CPrintInterface { virtual HRESULT QueryInterface(REFIID iid, void** ppvObj); virtual ULONG AddRef(); virtual ULONG Release(); virtual void PrintObject(); };

The implementations of AddRef and Release would be exactly the same as those implemented above. CPrintObj::QueryInterface would look something like this:

	Copy Code
HRESULT CPrintObj::QueryInterface(REFIID iid, void FAR* FAR* ppvObj) { if (iid == IID_IUnknown || iid == IID_IPrintInterface) { *ppvObj = this; AddRef(); return NOERROR; } return E_NOINTERFACE; }

As you can see, if the interface identifier (IID) is recognized, a pointer is returned to your object; otherwise an error occurs. Also note that a successful QueryInterface results in an implied AddRef. Of course, you'd also have to implement CEditObj::Print. That is simple because the IPrintInterface was directly derived from the IUnknown interface. However if you wanted to support two different interfaces, both derived from IUnknown, consider the following:

	Copy Code
class IEditInterface : public IUnkown { public: virtual void EditObject() = 0; };

Although there are a number of different ways to implement a class supporting both IEditInterface and IPrintInterface, including using C++ multiple inheritance, this note will concentrate on the use of nested classes to implement this functionality.

Copy Code

class CEditPrintObj { public: CEditPrintObj(); HRESULT QueryInterface(REFIID iid, void**); ULONG AddRef(); ULONG Release(); DWORD m_dwRef; class CPrintObj : public IPrintInterface { public: CEditPrintObj* m_pParent; virtual HRESULT QueryInterface(REFIID iid, void** ppvObj); virtual ULONG AddRef(); virtual ULONG Release(); } m_printObj; class CEditObj : public IEditInterface { public: CEditPrintObj* m_pParent; virtual ULONG QueryInterface(REFIID iid, void** ppvObj); virtual ULONG AddRef(); virtual ULONG Release(); } m_editObj; };

The entire implementation is included below:

Copy Code

CEditPrintObj::CEditPrintObj() { m_editObj.m_pParent = this; m_printObj.m_pParent = this; } ULONG CEditPrintObj::AddRef() { return ++m_dwRef; } CEditPrintObj::Release() { if (--m_dwRef == 0) { delete this; return 0; } return m_dwRef; } HRESULT CEditPrintObj::QueryInterface(REFIID iid, void** ppvObj) { if (iid == IID_IUnknown || iid == IID_IPrintInterface) { *ppvObj = &m_printObj; AddRef(); return NOERROR; } else if (iid == IID_IEditInterface) { *ppvObj = &m_editObj; AddRef(); return NOERROR; } return E_NOINTERFACE; } ULONG CEditPrintObj::CEditObj::AddRef() { return m_pParent->AddRef(); } ULONG CEditPrintObj::CEditObj::Release() { return m_pParent->Release(); } HRESULT CEditPrintObj::CEditObj::QueryInterface( REFIID iid, void** ppvObj) { return m_pParent->QueryInterface(iid, ppvObj); } ULONG CEditPrintObj::CPrintObj::AddRef() { return m_pParent->AddRef(); } ULONG CEditPrintObj::CPrintObj::Release() { return m_pParent->Release(); } HRESULT CEditPrintObj::CPrintObj::QueryInterface( REFIID iid, void** ppvObj) { return m_pParent->QueryInterface(iid, ppvObj); }

Notice that most of the IUnknown implementation is placed into the CEditPrintObj class rather than duplicating the code in CEditPrintObj::CEditObj and CEditPrintObj::CPrintObj. This reduces the amount of code and avoids bugs. The key point here is that from the IUnknown interface it is possible to call QueryInterface to retrieve any interface the object might support, and from each of those interfaces it is possible to do the same. This means that all QueryInterface functions available from each interface must behave exactly the same way. In order for these embedded objects to call the implementation in the "outer object", a back-pointer is used (m_pParent). The m_pParent pointer is initialized during the CEditPrintObj constructor. Then you would implement CEditPrintObj::CPrintObj::PrintObject and CEditPrintObj::CEditObj::EditObject as well. Quite a bit of code was added to add one feature — the ability to edit the object. Fortunately, it is quite uncommon for interfaces to have only a single member function (although it does happen) and in this case, EditObject and PrintObject would usually be combined into a single interface.

That's a lot of explanation and a lot of code for such a simple scenario. The MFC/OLE classes provide a simpler alternative. The MFC implementation uses a technique similar to the way Windows messages are wrapped with Message Maps. This facility is called Interface Maps and is discussed in the next section.

To implement a class using MFC's interface maps

The CPrintEditObj example above could be implemented as follows:

	Copy Code
class CPrintEditObj : public CCmdTarget { public: // member data and member functions for CPrintEditObj go here // Interface Maps protected: DECLARE_INTERFACE_MAP() BEGIN_INTERFACE_PART(EditObj, IEditInterface) STDMETHOD_(void, EditObject)(); END_INTERFACE_PART(EditObj) BEGIN_INTERFACE_PART(PrintObj, IPrintInterface) STDMETHOD_(void, PrintObject)(); END_INTERFACE_PART(PrintObj) };

The above declaration creates a class derived from CCmdTarget. The DECLARE_INTERFACE_MAP macro tells the framework that this class will have a custom interface map. In addition, the BEGIN_INTERFACE_PART and END_INTERFACE_PART macros define nested classes, in this case with names CEditObj and CPrintObj (the X is used only to differentiate the nested classes from global classes which start with "C" and interface classes which start with "I"). Two nested members of these classes are created: m_CEditObj, and m_CPrintObj, respectively. The macros automatically declare the AddRef, Release, and QueryInterface functions; therefore you only declare the functions specific to this interface: EditObject and PrintObject (the OLE macro STDMETHOD is used such so that _stdcall and virtual keywords are provided as appropriate for the target platform).

To implement the interface map for this class:

	Copy Code
BEGIN_INTERFACE_MAP(CPrintEditObj, CCmdTarget) INTERFACE_PART(CPrintEditObj, IID_IPrintInterface, PrintObj) INTERFACE_PART(CPrintEditObj, IID_IEditInterface, EditObj) END_INTERFACE_MAP()

This connects the IID_IPrintInterface IID with m_CPrintObj and IID_IEditInterface with m_CEditObj respectively. The CCmdTarget implementation of QueryInterface (CCmdTarget::ExternalQueryInterface) uses this map to return pointers to m_CPrintObj and m_CEditObj when requested. It is not necessary to include an entry for IID_IUnknown; the framework will use the first interface in the map (in this case, m_CPrintObj) when IID_IUnknown is requested.

Even though the BEGIN_INTERFACE_PART macro automatically declared the AddRef, Release and QueryInterface functions for you, you still need to implement them:

Copy Code

ULONG FAR EXPORT CEditPrintObj::XEditObj::AddRef() { METHOD_PROLOGUE(CEditPrintObj, EditObj) return pThis->ExternalAddRef(); } ULONG FAR EXPORT CEditPrintObj::XEditObj::Release() { METHOD_PROLOGUE(CEditPrintObj, EditObj) return pThis->ExternalRelease(); } HRESULT FAR EXPORT CEditPrintObj::XEditObj::QueryInterface( REFIID iid, void FAR* FAR* ppvObj) { METHOD_PROLOGUE(CEditPrintObj, EditObj) return (HRESULT)pThis->ExternalQueryInterface(&iid, ppvObj); } void FAR EXPORT CEditPrintObj::XEditObj::EditObject() { METHOD_PROLOGUE(CEditPrintObj, EditObj) // code to "Edit" the object, whatever that means... }

The implementation for CEditPrintObj::CPrintObj, would be similar to the above definitions for CEditPrintObj::CEditObj. Although it would be possible to create a macro that could be used to automatically generate these functions (but earlier in MFC/OLE development this was the case), it becomes difficult to set break points when a macro generates more than one line of code. For this reason, this code is expanded manually.

By using the framework implementation of message maps, there are a number of things that were not necessary to do:

• Implement QueryInterface

• Implement AddRef and Release

• Declare either of these built-in methods on both of your interfaces

In addition, the framework uses message maps internally. This allows you to derive from a framework class, say COleServerDoc, that already supports certain interfaces and provides either replacements or additions to the interfaces provided by the framework. This is enabled by the fact that the framework fully supports inheriting an interface map from a base class — that is the reason why BEGIN_INTERFACE_MAP takes as its second parameter the name of the base class.

Note:

It is generally not possible to reuse the implementation of MFC's built-in implementations of the OLE interfaces by inheriting the embedded specialization of that interface from the MFC version. This is not possible because the use of the METHOD_PROLOGUE macro to get access to the containing CCmdTarget-derived object implies a fixed offset of the embedded object from the CCmdTarget-derived object. This means, for example, you cannot derive an embedded XMyAdviseSink from MFC's implementation in COleClientItem::XAdviseSink, because XAdviseSink relies on being at a specific offset from the top of the COleClientItem object.

Note:

You can, however, delegate to the MFC implementation for all of the functions that you want MFC's default behavior. This is done in the MFC implementation of IOleInPlaceFrame (XOleInPlaceFrame) in the COleFrameHook class (it delegates to m_xOleInPlaceUIWindow for many functions). This design was chosen to reduce the runtime size of objects which implement many interfaces; it eliminates the need for a back-pointer (such as the way m_pParent was used in the previous section).

Aggregation and Interface Maps

Using an Aggregate Object

To use the INTERFACE_AGGREGATE macro

1. Declare a member variable (an IUnknown*) which will contain a pointer to the aggregate object.

2. Include an INTERFACE_AGGREGATE macro in your interface map, which refers to the member variable by name.

3. At some point (usually during CCmdTarget::OnCreateAggregates), initialize the member variable to something other than NULL.

For example:

Copy Code

class CAggrExample : public CCmdTarget { public: CAggrExample(); protected: LPUNKNOWN m_lpAggrInner; virtual BOOL OnCreateAggregates(); DECLARE_INTERFACE_MAP() // "native" interface part macros may be used here }; CAggrExample::CAggrExample() { m_lpAggrInner = NULL; } BOOL CAggrExample::OnCreateAggregates() { // wire up aggregate with correct controlling unknown m_lpAggrInner = CoCreateInstance(CLSID_Example, GetControllingUnknown(), CLSCTX_INPROC_SERVER, IID_IUnknown, (LPVOID*)&m_lpAggrInner); if (m_lpAggrInner == NULL) return FALSE; // optionally, create other aggregate objects here return TRUE; } BEGIN_INTERFACE_MAP(CAggrExample, CCmdTarget) // native "INTERFACE_PART" entries go here INTERFACE_AGGREGATE(CAggrExample, m_lpAggrInner) END_INTERFACE_MAP()

The m_lpAggrInner is initialized in the constructor to NULL. The framework will ignore a NULL member variable in the default implementation of QueryInterface. OnCreateAggregates is a good place to actually create your aggregate objects. You'll have to call it explicitly if you are creating the object outside of the MFC implementation of COleObjectFactory. The reason for creating aggregates in CCmdTarget::OnCreateAggregates as well as the usage of CCmdTarget::GetControllingUnknown will become apparent when creating aggregatable objects is discussed.

This technique will give your object all of the interfaces that the aggregate object supports plus its native interfaces. If you only want a subset of the interfaces that the aggregate supports, you can override CCmdTarget::GetInterfaceHook. This allows you very low-level hookability, similar to QueryInterface. Usually, you want all the interfaces that the aggregate supports.

Making an Object Implementation Aggregatable

Reference Material

CCmdTarget::EnableAggregation — Function Description

	Copy Code
voidEnableAggregation();