| description | title | ms.date | f1_keywords | helpviewer_keywords | ms.assetid | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Learn more about: Aggregation and Class Factory Macros |
Aggregation and Class Factory Macros |
08/12/2020 |
|
|
d99d379a-0eec-481f-8daa-252dac18f163 |
These macros provide ways of controlling aggregation and of declaring class factories.
| Macro | Description |
|---|---|
| DECLARE_AGGREGATABLE | Declares that your object can be aggregated (the default). |
| DECLARE_CLASSFACTORY | Declares the class factory to be CComClassFactory, the ATL default class factory. |
| DECLARE_CLASSFACTORY_EX | Declares your class factory object to be the class factory. |
| DECLARE_CLASSFACTORY2 | Declares CComClassFactory2 to be the class factory. |
| DECLARE_CLASSFACTORY_AUTO_THREAD | Declares CComClassFactoryAutoThread to be the class factory. |
| DECLARE_CLASSFACTORY_SINGLETON | Declares CComClassFactorySingleton to be the class factory. |
| DECLARE_GET_CONTROLLING_UNKNOWN | Declares a virtual GetControllingUnknown function. |
| DECLARE_NOT_AGGREGATABLE | Declares that your object cannot be aggregated. |
| DECLARE_ONLY_AGGREGATABLE | Declares that your object must be aggregated. |
| DECLARE_POLY_AGGREGATABLE | Checks the value of the outer unknown and declares your object aggregatable or not aggregatable, as appropriate. |
| DECLARE_PROTECT_FINAL_CONSTRUCT | Protects the outer object from deletion during construction of an inner object. |
| DECLARE_VIEW_STATUS | Specifies the VIEWSTATUS flags to the container. |
Header: atlcom.h
Specifies that your object can be aggregated.
DECLARE_AGGREGATABLE( x )x
[in] The name of the class you are defining as aggregatable.
CComCoClass contains this macro to specify the default aggregation model. To override this default, specify either the DECLARE_NOT_AGGREGATABLE or DECLARE_ONLY_AGGREGATABLE macro in your class definition.
[!code-cppNVC_ATL_Windowing#121]
Declares CComClassFactory to be the class factory.
DECLARE_CLASSFACTORY()CComCoClass uses this macro to declare the default class factory for your object.
[!code-cppNVC_ATL_COM#55]
This class implements the IClassFactory interface.
class CComClassFactory : public IClassFactory,
public CComObjectRootEx<CComGlobalsThreadModel>CComClassFactory implements the IClassFactory interface, which contains methods for creating an object of a particular CLSID, as well as locking the class factory in memory to allow new objects to be created more quickly. IClassFactory must be implemented for every class that you register in the system registry and to which you assign a CLSID.
ATL objects normally acquire a class factory by deriving from CComCoClass. This class includes the macro DECLARE_CLASSFACTORY, which declares CComClassFactory as the default class factory. To override this default, specify one of the DECLARE_CLASSFACTORYXXX macros in your class definition. For example, the DECLARE_CLASSFACTORY_EX macro uses the specified class for the class factory:
[!code-cppNVC_ATL_COM#8]
The above class definition specifies that CMyClassFactory will be used as the object's default class factory. CMyClassFactory must derive from CComClassFactory and override CreateInstance.
ATL provides three other macros that declare a class factory:
-
DECLARE_CLASSFACTORY2 Uses CComClassFactory2, which controls creation through a license.
-
DECLARE_CLASSFACTORY_AUTO_THREAD Uses CComClassFactoryAutoThread, which creates objects in multiple apartments.
-
DECLARE_CLASSFACTORY_SINGLETON Uses CComClassFactorySingleton, which constructs a single CComObjectGlobal object.
Declares cf to be the class factory.
DECLARE_CLASSFACTORY_EX( cf )cf
[in] The name of the class that implements your class factory object.
The cf parameter must derive from CComClassFactory and override the CreateInstance method.
CComCoClass includes the DECLARE_CLASSFACTORY macro, which specifies CComClassFactory as the default class factory. However, by including the DECLARE_CLASSFACTORY_EX macro in your object's class definition, you override this default.
[!code-cppNVC_ATL_COM#8]
Declares CComClassFactory2 to be the class factory.
DECLARE_CLASSFACTORY2( lic )lic
[in] A class that implements VerifyLicenseKey, GetLicenseKey, and IsLicenseValid.
CComCoClass includes the DECLARE_CLASSFACTORY macro, which specifies CComClassFactory as the default class factory. However, by including the DECLARE_CLASSFACTORY2 macro in your object's class definition, you override this default.
[!code-cppNVC_ATL_COM#2]
This class implements the IClassFactory2 interface.
template <class license>
class CComClassFactory2 : public IClassFactory2,
public CComObjectRootEx<CComGlobalsThreadModel>,
public licenselicense
A class that implements the following static functions:
-
static BOOL VerifyLicenseKey( BSTR bstr ); -
static BOOL GetLicenseKey( DWORD dwReserved, BSTR * pBstr ); -
static BOOL IsLicenseValid( );
CComClassFactory2 implements the IClassFactory2 interface, which is an extension of IClassFactory. IClassFactory2 controls object creation through a license. A class factory executing on a licensed machine can provide a run-time license key. This license key allows an application to instantiate objects when a full machine license does not exist.
ATL objects normally acquire a class factory by deriving from CComCoClass. This class includes the macro DECLARE_CLASSFACTORY, which declares CComClassFactory as the default class factory. To use CComClassFactory2, specify the DECLARE_CLASSFACTORY2 macro in your object's class definition. For example:
[!code-cppNVC_ATL_COM#2]
CMyLicense, the template parameter to CComClassFactory2, must implement the static functions VerifyLicenseKey, GetLicenseKey, and IsLicenseValid. The following is an example of a simple license class:
[!code-cppNVC_ATL_COM#3]
CComClassFactory2 derives from both CComClassFactory2Base and license. CComClassFactory2Base, in turn, derives from IClassFactory2 and CComObjectRootEx< CComGlobalsThreadModel >.
Declares CComClassFactoryAutoThread to be the class factory.
DECLARE_CLASSFACTORY_AUTO_THREAD()CComCoClass includes the DECLARE_CLASSFACTORY macro, which specifies CComClassFactory as the default class factory. However, by including the DECLARE_CLASSFACTORY_AUTO_THREAD macro in your object's class definition, you override this default.
When you create objects in multiple apartments (in an out-of-proc server), add DECLARE_CLASSFACTORY_AUTO_THREAD to your class.
[!code-cppNVC_ATL_COM#9]
This class implements the IClassFactory interface, and allows objects to be created in multiple apartments.
Important
This class and its members cannot be used in applications that execute in the Windows Runtime.
class CComClassFactoryAutoThread : public IClassFactory,
public CComObjectRootEx<CComGlobalsThreadModel>CComClassFactoryAutoThread is similar to CComClassFactory, but allows objects to be created in multiple apartments. To take advantage of this support, derive your EXE module from CComAutoThreadModule.
ATL objects normally acquire a class factory by deriving from CComCoClass. This class includes the macro DECLARE_CLASSFACTORY, which declares CComClassFactory as the default class factory. To use CComClassFactoryAutoThread, specify the DECLARE_CLASSFACTORY_AUTO_THREAD macro in your object's class definition. For example:
[!code-cppNVC_ATL_COM#9]
Declares CComClassFactorySingleton to be the class factory.
DECLARE_CLASSFACTORY_SINGLETON( obj )obj
[in] The name of your class object.
CComCoClass includes the DECLARE_CLASSFACTORY macro, which specifies CComClassFactory as the default class factory. However, by including the DECLARE_CLASSFACTORY_SINGLETON macro in your object's class definition, you override this default.
[!code-cppNVC_ATL_COM#10]
This class derives from CComClassFactory and uses CComObjectGlobal to construct a single object.
Important
This class and its members cannot be used in applications that execute in the Windows Runtime.
template<class T>
class CComClassFactorySingleton : public CComClassFactoryT
Your class.
CComClassFactorySingleton derives from CComClassFactory and uses CComObjectGlobal to construct a single object. Each call to the CreateInstance method simply queries this object for an interface pointer.
ATL objects normally acquire a class factory by deriving from CComCoClass. This class includes the macro DECLARE_CLASSFACTORY, which declares CComClassFactory as the default class factory. To use CComClassFactorySingleton, specify the DECLARE_CLASSFACTORY_SINGLETON macro in your object's class definition. For example:
[!code-cppNVC_ATL_COM#10]
Declares a virtual function GetControllingUnknown.
DECLARE_GET_CONTROLLING_UNKNOWN()Add this macro to your object if you get the compiler error message that GetControllingUnknown is undefined (for example, in CComAggregateCreator).
Specifies that your object cannot be aggregated.
DECLARE_NOT_AGGREGATABLE( x )x
[in] The name of the class object you are defining as not aggregatable.
DECLARE_NOT_AGGREGATABLE causes CreateInstance to return an error (CLASS_E_NOAGGREGATION) if an attempt is made to aggregate onto your object.
By default, CComCoClass contains the DECLARE_AGGREGATABLE macro, which specifies that your object can be aggregated. To override this default behavior, include DECLARE_NOT_AGGREGATABLE in your class definition.
[!code-cppNVC_ATL_Windowing#121]
Specifies that your object must be aggregated.
DECLARE_ONLY_AGGREGATABLE( x )x
[in] The name of the class object you are defining as only aggregatable.
DECLARE_ONLY_AGGREGATABLE causes an error (E_FAIL) if an attempt is made to CoCreate your object as nonaggregated object.
By default, CComCoClass contains the DECLARE_AGGREGATABLE macro, which specifies that your object can be aggregated. To override this default behavior, include DECLARE_ONLY_AGGREGATABLE in your class definition.
[!code-cppNVC_ATL_Windowing#125]
Specifies that an instance of CComPolyObject < x > is created when your object is created.
DECLARE_POLY_AGGREGATABLE( x )x
[in] The name of the class object you are defining as aggregatable or not aggregatable.
During creation, the value of the outer unknown is checked. If it is NULL, IUnknown is implemented for a nonaggregated object. If the outer unknown is not NULL, IUnknown is implemented for an aggregated object.
The advantage of using DECLARE_POLY_AGGREGATABLE is that you avoid having both CComAggObject and CComObject in your module to handle the aggregated and nonaggregated cases. A single CComPolyObject object handles both cases. This means only one copy of the vtable and one copy of the functions exist in your module. If your vtable is large, this can substantially decrease your module size. However, if your vtable is small, using CComPolyObject can result in a slightly larger module size because it is not optimized for an aggregated or nonaggregated object, as are CComAggObject and CComObject.
The DECLARE_POLY_AGGREGATABLE macro is automatically declared in your object if you use the ATL Control Wizard to create a full control.
Protects your object from being deleted if (during FinalConstruct) the internal aggregated object increments the reference count then decrements the count to 0.
DECLARE_PROTECT_FINAL_CONSTRUCT()Place this macro in an ATL ActiveX control's control class to specify the VIEWSTATUS flags to the container.
DECLARE_VIEW_STATUS( statusFlags )statusFlags
[in] The VIEWSTATUS flags. See VIEWSTATUS for a list of flags.
[!code-cppNVC_ATL_Windowing#126]