Fundamentals of ATL COM Objects
The latest version of this topic can be found at Fundamentals of ATL COM Objects.
The following illustration depicts the relationship among the classes and interfaces that are used to define an ATL COM object.
.jpeg "ATL structure")
Note
This diagram shows that CComObject is derived from CYourClass whereas CComAggObject and CComPolyObject include CYourClass as a member variable.
There are three ways to define an ATL COM object. The standard option is to use the CComObject class which is derived from CYourClass. The second option is to create an aggregated object by using the CComAggObject class. The third option is to use the CComPolyObject class. CComPolyObject acts as a hybrid: it can function as a CComObject class or as a CComAggObject class, depending on how it is first created. For more information about how to use the CComPolyObject class, see CComPolyObject Class.
When you use standard ATL COM, you use two objects: an outer object and an inner object. External clients access the functionality of the inner object through the wrapper functions that are defined in the outer object. The outer object is of type CComObject.
When you use an aggregated object, the outer object does not provide wrappers for the functionality of the inner object. Instead, the outer object provides a pointer that is directly accessed by external clients. In this scenario, the outer object is of type CComAggObject. The inner object is a member variable of the outer object, and it is of type CYourClass.
Because the client does not have to go through the outer object to interact with the inner object, aggregated objects are usually more efficient. Also, the outer object does not have to know the functionality of the aggregated object, given that the interface of the aggregated object is directly available to the client. However, not all objects can be aggregated. For an object to be aggregated, it needs to be designed with aggregation in mind.
ATL implements IUnknown in two phases:
CComObject, CComAggObject, or CComPolyObject implements the IUnknown methods.
CComObjectRoot or CComObjectRootEx manages the reference count and outer pointers of IUnknown.
Other aspects of your ATL COM object are handled by other classes:
CComCoClass defines the object's default class factory and aggregation model.
IDispatchImpl provides a default implementation of the
IDispatch Interfaceportion of any dual interfaces on the object.ISupportErrorInfoImpl implements the ISupportErrorInfo interface that ensures error information can be propagated up the call chain correctly.
In This Section
Implementing CComObjectRootEx
Show example COM map entries for implementing CComObjectRootEx.
Implementing CComObject, CComAggObject, and CComPolyObject
Discusses how the DECLARE_*_AGGREGATABLE macros affect the use of CComObject, CComAggObject, and CComPolyObject.
Supporting IDispatch and IErrorInfo
Lists the ATL implementation classes to use for supporting the IDispatch and IErrorInfo interfaces.
Supporting IDispEventImpl
Discusses the steps to implement a connection point for your class.
Changing the Default Class Factory and Aggregation Model
Show what macros to use to change the default class factory and aggregation model.
Creating an Aggregated Object
Lists the steps for creating an aggregated object.
Related Sections
Creating an ATL Project
Provides information about creating an ATL COM object.
ATL
Provides links to conceptual topics on how to program using the Active Template Library.