Aggregation und Klassenfactory-Makros

  • Artikel

Diese Makros bieten Möglichkeiten zum Steuern der Aggregation und zum Deklarieren von Klassenfabriken.

Makro Beschreibung
DECLARE_AGGREGATABLE Deklariert, dass Ihr Objekt aggregiert werden kann (standard).
DECLARE_CLASSFACTORY Deklariert die Klassenfactory als CComClassFactory, die ATL-Standardklassenfactory.
DECLARE_CLASSFACTORY_EX Deklariert das Klassenfactoryobjekt als Klassenfactory.
DECLARE_CLASSFACTORY2 Deklariert CComClassFactory2 als Klassenfactory.
DECLARE_CLASSFACTORY_AUTO_THREAD Deklariert CComClassFactoryAutoThread als Klassenfactory.
DECLARE_CLASSFACTORY_SINGLETON Deklariert CComClassFactorySingleton als Klassenfactory.
DECLARE_GET_CONTROLLING_UNKNOWN Deklariert eine virtuelle GetControllingUnknown Funktion.
DECLARE_NOT_AGGREGATABLE Deklariert, dass das Objekt nicht aggregiert werden kann.
DECLARE_ONLY_AGGREGATABLE Deklariert, dass das Objekt aggregiert werden muss.
DECLARE_POLY_AGGREGATABLE Überprüft den Wert des äußeren Unbekannten und deklariert das aggregatierbare oder nicht aggregierbare Objekt entsprechend.
DECLARE_PROTECT_FINAL_CONSTRUCT Schützt das äußere Objekt vor dem Löschen während der Konstruktion eines inneren Objekts.
DECLARE_VIEW_STATUS Gibt die VIEWSTATUS-Flags für den Container an.

Anforderungen

Kopfzeile: atlcom.h

DECLARE_AGGREGATABLE

Gibt an, dass Ihr Objekt aggregiert werden kann.

DECLARE_AGGREGATABLE( x )

Parameter

x
[in] Der Name der Klasse, die Sie als aggregierbar definieren.

Hinweise

CComCoClass enthält dieses Makro, um das Standardaggregationsmodell anzugeben. Um diese Standardeinstellung außer Kraft zu setzen, geben Sie entweder das DECLARE_NOT_AGGREGATABLE - oder DECLARE_ONLY_AGGREGATABLE Makro in der Klassendefinition an.

Beispiel

class ATL_NO_VTABLE CNoAggClass :
   public CComObjectRoot,
   public CComCoClass<CNoAggClass, &CLSID_NoAggClass>
{
public:
   CNoAggClass()
   {
   }

   DECLARE_NOT_AGGREGATABLE(CNoAggClass)
};

DECLARE_CLASSFACTORY

Deklariert CComClassFactory als Klassenfactory.

DECLARE_CLASSFACTORY()

Hinweise

CComCoClass verwendet dieses Makro, um die Standardklassenfactory für Ihr Objekt zu deklarieren.

Beispiel

class ATL_NO_VTABLE CMyClass :
   public CComObjectRootEx<CComSingleThreadModel>,
   public CComCoClass<CMyClass, &CLSID_MyClass>,
   public IDispatchImpl<IMyClass, &IID_IMyClass, &LIBID_NVC_ATL_COMLib, /*wMajor =*/ 1, /*wMinor =*/ 0>,
   public IDispatchImpl<IMyDualInterface, &__uuidof(IMyDualInterface), &LIBID_NVC_ATL_COMLib, /* wMajor = */ 1, /* wMinor = */ 0>
{
public:
   DECLARE_CLASSFACTORY()

   // Remainder of class declaration omitted

CComClassFactory-Klasse

Diese Klasse implementiert die IClassFactory-Schnittstelle .

class CComClassFactory : public IClassFactory,
public CComObjectRootEx<CComGlobalsThreadModel>

Hinweise

CComClassFactory implementiert die IClassFactory-Schnittstelle , die Methoden zum Erstellen eines Objekts einer bestimmten CLSID enthält, sowie das Sperren der Klassenfactory im Arbeitsspeicher, damit neue Objekte schneller erstellt werden können. IClassFactory muss für jede Klasse implementiert werden, die Sie in der Systemregistrierung registrieren und der Sie eine CLSID zuweisen.

ATL-Objekte erwerben normalerweise eine Klassenfactory, indem sie von CComCoClass abgeleitet wird. Diese Klasse enthält das Makro DECLARE_CLASSFACTORY, das als Standardklassenfactory deklariert wird CComClassFactory . Um diese Standardeinstellung außer Kraft zu setzen, geben Sie eines der DECLARE_CLASSFACTORYXXX-Makros in Ihrer Klassendefinition an. Beispielsweise verwendet das DECLARE_CLASSFACTORY_EX-Makro die angegebene Klasse für die Klassenfactory:

class ATL_NO_VTABLE CMyCustomClass :
   public CComObjectRootEx<CComSingleThreadModel>,
   public CComCoClass<CMyCustomClass, &CLSID_MyCustomClass>,
   public IDispatchImpl<IMyCustomClass, &IID_IMyCustomClass, &LIBID_NVC_ATL_COMLib, /*wMajor =*/ 1, /*wMinor =*/ 0>
{
public:
   DECLARE_CLASSFACTORY_EX(CMyClassFactory)

   // Remainder of class declaration omitted.

Die obige Klassendefinition gibt an, dass CMyClassFactory als Standardklassenfactory des Objekts verwendet wird. CMyClassFactory muss von CComClassFactory und außer Kraft setzen CreateInstance.

ATL stellt drei weitere Makros bereit, die eine Klassenfactory deklarieren:

DECLARE_CLASSFACTORY_EX

cf Deklariert als Klassenfactory.

DECLARE_CLASSFACTORY_EX( cf )

Parameter

vgl
[in] Der Name der Klasse, die Ihr Klassenfactoryobjekt implementiert.

Hinweise

Der cf-Parameter muss von CComClassFactory abgeleitet und die CreateInstance Methode überschreiben.

CComCoClass enthält das DECLARE_CLASSFACTORY-Makro , das als Standardklassenfactory angibt CComClassFactory . Indem Sie jedoch das DECLARE_CLASSFACTORY_EX Makro in die Klassendefinition Ihres Objekts einschließen, setzen Sie diese Standardeinstellung außer Kraft.

Beispiel

class ATL_NO_VTABLE CMyCustomClass :
   public CComObjectRootEx<CComSingleThreadModel>,
   public CComCoClass<CMyCustomClass, &CLSID_MyCustomClass>,
   public IDispatchImpl<IMyCustomClass, &IID_IMyCustomClass, &LIBID_NVC_ATL_COMLib, /*wMajor =*/ 1, /*wMinor =*/ 0>
{
public:
   DECLARE_CLASSFACTORY_EX(CMyClassFactory)

   // Remainder of class declaration omitted.

DECLARE_CLASSFACTORY2

Deklariert CComClassFactory2 als Klassenfactory.

DECLARE_CLASSFACTORY2( lic )

Parameter

lic
[in] Eine Klasse, die VerifyLicenseKey, GetLicenseKeyund IsLicenseValid.

Hinweise

CComCoClass enthält das DECLARE_CLASSFACTORY-Makro, das CComClassFactory als Standardklassenfactory angibt. Indem Sie jedoch das DECLARE_CLASSFACTORY2 Makro in die Klassendefinition Ihres Objekts einschließen, setzen Sie diese Standardeinstellung außer Kraft.

Beispiel

class ATL_NO_VTABLE CMyClass2 :
   public CComObjectRootEx<CComSingleThreadModel>,
   public CComCoClass<CMyClass2, &CLSID_MyClass>,
   public IDispatchImpl<IMyClass, &IID_IMyClass, &LIBID_NVC_ATL_COMLib, /*wMajor =*/ 1, /*wMinor =*/ 0>,
   public IDispatchImpl<IMyDualInterface, &__uuidof(IMyDualInterface), &LIBID_NVC_ATL_COMLib, /* wMajor = */ 1, /* wMinor = */ 0>
{
public:
   DECLARE_CLASSFACTORY2(CMyLicense)

   // Remainder of class declaration omitted

CComClassFactory2-Klasse

Diese Klasse implementiert die IClassFactory2-Schnittstelle .

template <class license>
class  CComClassFactory2 : public IClassFactory2,
    public CComObjectRootEx<CComGlobalsThreadModel>,
    public license

Parameter

license
Eine Klasse, die die folgenden statischen Funktionen implementiert:

  • static BOOL VerifyLicenseKey( BSTR bstr );

  • static BOOL GetLicenseKey( DWORD dwReserved, BSTR * pBstr );

  • static BOOL IsLicenseValid( );

Hinweise

CComClassFactory2 implementiert die IClassFactory2-Schnittstelle , die eine Erweiterung von IClassFactory ist. IClassFactory2 steuert die Objekterstellung über eine Lizenz. Eine Klassenfactory, die auf einem lizenzierten Computer ausgeführt wird, kann einen Laufzeitlizenzschlüssel bereitstellen. Mit diesem Lizenzschlüssel kann eine Anwendung Objekte instanziieren, wenn keine vollständige Computerlizenz vorhanden ist.

ATL-Objekte erwerben normalerweise eine Klassenfactory, indem sie von CComCoClass abgeleitet wird. Diese Klasse enthält das Makro DECLARE_CLASSFACTORY, das CComClassFactory als Standardklassenfactory deklariert. Geben Sie zum Verwenden CComClassFactory2das DECLARE_CLASSFACTORY2 Makro in der Klassendefinition des Objekts an. Zum Beispiel:

class ATL_NO_VTABLE CMyClass2 :
   public CComObjectRootEx<CComSingleThreadModel>,
   public CComCoClass<CMyClass2, &CLSID_MyClass>,
   public IDispatchImpl<IMyClass, &IID_IMyClass, &LIBID_NVC_ATL_COMLib, /*wMajor =*/ 1, /*wMinor =*/ 0>,
   public IDispatchImpl<IMyDualInterface, &__uuidof(IMyDualInterface), &LIBID_NVC_ATL_COMLib, /* wMajor = */ 1, /* wMinor = */ 0>
{
public:
   DECLARE_CLASSFACTORY2(CMyLicense)

   // Remainder of class declaration omitted

CMyLicense, der Vorlagenparameter für CComClassFactory2, muss die statischen Funktionen VerifyLicenseKeyGetLicenseKey, , und IsLicenseValid. Im Folgenden sehen Sie ein Beispiel für eine einfache Lizenzklasse:

class CMyLicense
{
protected:
   static BOOL VerifyLicenseKey(BSTR bstr)
   {
      USES_CONVERSION;
      return !lstrcmp(OLE2T(bstr), _T("My run-time license key"));
   }

   static BOOL GetLicenseKey(DWORD /*dwReserved*/, BSTR* pBstr) 
   {
      USES_CONVERSION;
      *pBstr = SysAllocString( T2OLE(_T("My run-time license key"))); 
      return TRUE;
   }

   static BOOL IsLicenseValid() {  return TRUE; }
};

CComClassFactory2abgeleitet von sowohl als auch CComClassFactory2Base von der Lizenz. CComClassFactory2Base, wiederum abgeleitet von IClassFactory2 und CComObjectRootEx< CComGlobalsThreadModel >.

DECLARE_CLASSFACTORY_AUTO_THREAD

Deklariert CComClassFactoryAutoThread als Klassenfactory.

DECLARE_CLASSFACTORY_AUTO_THREAD()

Hinweise

CComCoClass enthält das DECLARE_CLASSFACTORY-Makro, das CComClassFactory als Standardklassenfactory angibt. Indem Sie jedoch das DECLARE_CLASSFACTORY_AUTO_THREAD Makro in die Klassendefinition Ihres Objekts einschließen, setzen Sie diese Standardeinstellung außer Kraft.

Wenn Sie Objekte in mehreren Wohnungen (in einem out-of-proc-Server) erstellen, fügen Sie Ihrer Klasse DECLARE_CLASSFACTORY_AUTO_THREAD hinzu.

Beispiel

class ATL_NO_VTABLE CMyAutoClass :
   public CComObjectRootEx<CComMultiThreadModel>,
   public CComCoClass<CMyAutoClass, &CLSID_MyAutoClass>,
   public IMyAutoClass
{
public:
   DECLARE_CLASSFACTORY_AUTO_THREAD()

   // Remainder of class declaration omitted.

CComClassFactoryAutoThread-Klasse

Diese Klasse implementiert die IClassFactory-Schnittstelle und ermöglicht das Erstellen von Objekten in mehreren Wohnungen.

Wichtig

Diese Klasse und ihre Member können nicht in Anwendungen verwendet werden, die in der Windows-Runtime ausgeführt werden.

class CComClassFactoryAutoThread : public IClassFactory,
public CComObjectRootEx<CComGlobalsThreadModel>

Hinweise

CComClassFactoryAutoThreadähnelt CComClassFactory, ermöglicht jedoch die Erstellung von Objekten in mehreren Wohnungen. Um diese Unterstützung nutzen zu können, leiten Sie Ihr EXE-Modul von CComAutoThreadModule ab.

ATL-Objekte erwerben normalerweise eine Klassenfactory, indem sie von CComCoClass abgeleitet wird. Diese Klasse enthält das Makro DECLARE_CLASSFACTORY, das CComClassFactory als Standardklassenfactory deklariert. Geben Sie zum Verwenden CComClassFactoryAutoThreaddas DECLARE_CLASSFACTORY_AUTO_THREAD Makro in der Klassendefinition des Objekts an. Zum Beispiel:

class ATL_NO_VTABLE CMyAutoClass :
   public CComObjectRootEx<CComMultiThreadModel>,
   public CComCoClass<CMyAutoClass, &CLSID_MyAutoClass>,
   public IMyAutoClass
{
public:
   DECLARE_CLASSFACTORY_AUTO_THREAD()

   // Remainder of class declaration omitted.

DECLARE_CLASSFACTORY_SINGLETON

Deklariert CComClassFactorySingleton als Klassenfactory.

DECLARE_CLASSFACTORY_SINGLETON( obj )

Parameter

obj
[in] Der Name des Klassenobjekts.

Hinweise

CComCoClass enthält das DECLARE_CLASSFACTORY-Makro, das CComClassFactory als Standardklassenfactory angibt. Indem Sie jedoch das DECLARE_CLASSFACTORY_SINGLETON Makro in die Klassendefinition Ihres Objekts einschließen, setzen Sie diese Standardeinstellung außer Kraft.

Beispiel

class ATL_NO_VTABLE CMySingletonClass :
   public CComObjectRootEx<CComSingleThreadModel>,
   public CComCoClass<CMySingletonClass, &CLSID_MySingletonClass>,
   public IMySingletonClass
{
public:
   DECLARE_CLASSFACTORY_SINGLETON(CMySingletonClass)

   // Remainder of class declaration omitted.

CComClassFactorySingleton-Klasse

Diese Klasse wird von CComClassFactory abgeleitet und verwendet CComObjectGlobal , um ein einzelnes Objekt zu erstellen.

Wichtig

Diese Klasse und ihre Member können nicht in Anwendungen verwendet werden, die in der Windows-Runtime ausgeführt werden.

template<class T>
class CComClassFactorySingleton : public CComClassFactory

Parameter

T
Ihr Kurs.

CComClassFactorySingleton abgeleitet von CComClassFactory und verwendet CComObjectGlobal , um ein einzelnes Objekt zu erstellen. Jeder Aufruf der CreateInstance Methode fragt dieses Objekt einfach nach einem Schnittstellenzeiger ab.

Hinweise

ATL-Objekte erwerben normalerweise eine Klassenfactory, indem sie von CComCoClass abgeleitet wird. Diese Klasse enthält das Makro DECLARE_CLASSFACTORY, das als Standardklassenfactory deklariert wird CComClassFactory . Geben Sie zum Verwenden CComClassFactorySingletondas DECLARE_CLASSFACTORY_SINGLETON Makro in der Klassendefinition des Objekts an. Zum Beispiel:

class ATL_NO_VTABLE CMySingletonClass :
   public CComObjectRootEx<CComSingleThreadModel>,
   public CComCoClass<CMySingletonClass, &CLSID_MySingletonClass>,
   public IMySingletonClass
{
public:
   DECLARE_CLASSFACTORY_SINGLETON(CMySingletonClass)

   // Remainder of class declaration omitted.

DECLARE_GET_CONTROLLING_UNKNOWN

Deklariert eine virtuelle Funktion GetControllingUnknown.

DECLARE_GET_CONTROLLING_UNKNOWN()

Hinweise

Fügen Sie dieses Makro zu Ihrem Objekt hinzu, wenn Sie die nicht definierte Compilerfehlermeldung GetControllingUnknown erhalten (z. B. in CComAggregateCreator).

DECLARE_NOT_AGGREGATABLE

Gibt an, dass Ihr Objekt nicht aggregiert werden kann.

DECLARE_NOT_AGGREGATABLE( x )

Parameter

x
[in] Der Name des Klassenobjekts, das Sie definieren, ist nicht aggregierbar.

Hinweise

DECLARE_NOT_AGGREGATABLE bewirkt CreateInstance , dass ein Fehler (CLASS_E_NOAGGREGATION) zurückgegeben wird, wenn versucht wird, das Objekt zu aggregieren.

Standardmäßig enthält CComCoClass das DECLARE_AGGREGATABLE Makro, das angibt, dass Ihr Objekt aggregiert werden kann. Um dieses Standardverhalten außer Kraft zu setzen, schließen Sie DECLARE_NOT_AGGREGATABLE in die Klassendefinition ein.

Beispiel

class ATL_NO_VTABLE CNoAggClass :
   public CComObjectRoot,
   public CComCoClass<CNoAggClass, &CLSID_NoAggClass>
{
public:
   CNoAggClass()
   {
   }

   DECLARE_NOT_AGGREGATABLE(CNoAggClass)
};

DECLARE_ONLY_AGGREGATABLE

Gibt an, dass Das Objekt aggregiert werden muss.

DECLARE_ONLY_AGGREGATABLE( x )

Parameter

x
[in] Der Name des Klassenobjekts, das Sie definieren, ist nur aggregierbar.

Hinweise

DECLARE_ONLY_AGGREGATABLE verursacht einen Fehler (E_FAIL), wenn versucht wird, das Objekt als nicht aggregiertes Objekt zu CoCreate verwenden.

Standardmäßig enthält CComCoClass das DECLARE_AGGREGATABLE Makro, das angibt, dass Ihr Objekt aggregiert werden kann. Um dieses Standardverhalten außer Kraft zu setzen, fügen Sie DECLARE_ONLY_AGGREGATABLE in die Klassendefinition ein.

Beispiel

class ATL_NO_VTABLE COnlyAggClass :
   public CComObjectRoot,
   public CComCoClass<COnlyAggClass, &CLSID_OnlyAggClass>
{
public:
   COnlyAggClass()
   {
   }

   DECLARE_ONLY_AGGREGATABLE(COnlyAggClass)
};

DECLARE_POLY_AGGREGATABLE

Gibt an, dass beim Erstellen des Objekts eine Instanz von CComPolyObject < x > erstellt wird.

DECLARE_POLY_AGGREGATABLE( x )

Parameter

x
[in] Der Name des Klassenobjekts, das Sie als aggregierbar oder nicht aggregierbar definieren.

Hinweise

Während der Erstellung wird der Wert des äußeren Unbekannten überprüft. Wenn es NULL ist, IUnknown wird für ein nicht aggregiertes Objekt implementiert. Wenn das äußere Unbekannte nicht NULL ist, IUnknown wird für ein aggregiertes Objekt implementiert.

Der Vorteil der Verwendung von DECLARE_POLY_AGGREGATABLE besteht darin, dass Sie sowohl als auch CComAggObject CComObject in Ihrem Modul vermeiden, die aggregierten und nicht aggregierten Fälle zu verarbeiten. Ein einzelnes CComPolyObject Objekt behandelt beide Fälle. Dies bedeutet, dass nur eine Kopie der vtable und eine Kopie der Funktionen in Ihrem Modul vorhanden ist. Wenn die vtable groß ist, kann dies die Modulgröße erheblich verringern. Wenn die vtable jedoch klein ist, kann die Verwendung CComPolyObject zu einer etwas größeren Modulgröße führen, da sie nicht für ein aggregiertes oder nicht aggregiertes Objekt optimiert ist, wie es sind CComAggObject und CComObject.

Das DECLARE_POLY_AGGREGATABLE Makro wird automatisch in Ihrem Objekt deklariert, wenn Sie den ATL-Steuerelement-Assistenten zum Erstellen eines Vollzugriffs verwenden.

DECLARE_PROTECT_FINAL_CONSTRUCT

Schützt, dass Ihr Objekt gelöscht wird, wenn (während FinalConstruct) das interne aggregierte Objekt die Verweisanzahl erhöht und dann die Anzahl auf 0 erhöht.

DECLARE_PROTECT_FINAL_CONSTRUCT()

DECLARE_VIEW_STATUS

Platzieren Sie dieses Makro in der Steuerelementklasse eines ATL-ActiveX-Steuerelements, um die VIEWSTATUS-Flags für den Container anzugeben.

DECLARE_VIEW_STATUS( statusFlags )

Parameter

statusFlags
[in] Die VIEWSTATUS-Flags. Eine Liste von Flags finden Sie unter VIEWSTATUS .

Beispiel

DECLARE_VIEW_STATUS(VIEWSTATUS_SOLIDBKGND | VIEWSTATUS_OPAQUE)

Siehe auch

Makros