Fundamentals of ATL COM Objects
For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.
The following illustration depicts the relationship among the classes and interfaces that are used to define an ATL COM object.
This diagram shows that
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 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
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
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:
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.
Show example COM map entries for implementing
Implementing CComObject, CComAggObject, and CComPolyObject
Discusses how the DECLARE_*_AGGREGATABLE macros affect the use of
Supporting IDispatch and IErrorInfo
Lists the ATL implementation classes to use for supporting the
IDispatch and IErrorInfo interfaces.
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.
Creating an ATL Project
Provides information about creating an ATL COM object.
Provides links to conceptual topics on how to program using the Active Template Library.