Agregační makra a makra objektu pro vytváření tříd

Článek
10/12/2023

Tato makra poskytují způsoby řízení agregace a deklarování továren tříd.

Makro	Popis
DECLARE_AGGREGATABLE	Deklaruje, že objekt lze agregovat (výchozí).
DECLARE_CLASSFACTORY	Deklaruje objekt pro vytváření tříd jako CComClassFactory, výchozí objekt pro vytváření tříd ATL.
DECLARE_CLASSFACTORY_EX	Deklaruje objekt objektu objektu pro vytváření tříd jako objekt pro vytváření tříd.
DECLARE_CLASSFACTORY2	Deklaruje CComClassFactory2 jako objekt pro vytváření tříd.
DECLARE_CLASSFACTORY_AUTO_THREAD	Deklaruje CComClassFactoryAutoThread jako objekt pro vytváření tříd.
DECLARE_CLASSFACTORY_SINGLETON	Deklaruje CComClassFactorySingleton jako objekt pro vytváření tříd.
DECLARE_GET_CONTROLLING_UNKNOWN	Deklaruje virtuální `GetControllingUnknown` funkci.
DECLARE_NOT_AGGREGATABLE	Deklaruje, že objekt nelze agregovat.
DECLARE_ONLY_AGGREGATABLE	Deklaruje, že objekt musí být agregován.
DECLARE_POLY_AGGREGATABLE	Zkontroluje hodnotu vnějšího neznámého objektu a podle potřeby deklaruje agregatable nebo není agregatable.
DECLARE_PROTECT_FINAL_CONSTRUCT	Chrání vnější objekt před odstraněním během vytváření vnitřního objektu.
DECLARE_VIEW_STATUS	Určuje příznaky VIEWSTATUS kontejneru.

Požadavky

Hlavička: atlcom.h

DECLARE_AGGREGATABLE

Určuje, že objekt lze agregovat.

DECLARE_AGGREGATABLE( x )

Parametry

x
[v] Název třídy, kterou definujete jako agregatable.

Poznámky

CComCoClass obsahuje toto makro k určení výchozího agregačního modelu. Chcete-li toto výchozí nastavení přepsat, zadejte v definici třídy buď DECLARE_NOT_AGGREGATABLE , nebo DECLARE_ONLY_AGGREGATABLE makro.

Příklad

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

   DECLARE_NOT_AGGREGATABLE(CNoAggClass)
};

DECLARE_CLASSFACTORY

Deklaruje CComClassFactory jako objekt pro vytváření tříd.

DECLARE_CLASSFACTORY()

Poznámky

CComCoClass používá toto makro k deklarování výchozí objektu pro vytváření tříd pro objekt.

Příklad

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 – třída

Tato třída implementuje IClassFactory rozhraní.

class CComClassFactory : public IClassFactory,
public CComObjectRootEx<CComGlobalsThreadModel>

Poznámky

CComClassFactory implementuje IClassFactory rozhraní, které obsahuje metody pro vytvoření objektu konkrétní CLSID, stejně jako uzamčení objektu pro vytváření tříd v paměti, aby bylo možné vytvářet nové objekty rychleji. IClassFactory musí být implementována pro každou třídu, kterou zaregistrujete v systémovém registru a ke které přiřadíte CLSID.

Objekty ATL obvykle získávají objekt pro vytváření tříd odvozením z CComCoClass. Tato třída obsahuje DECLARE_CLASSFACTORY makra, které deklaruje CComClassFactory jako výchozí objekt pro vytváření tříd. Chcete-li toto výchozí nastavení přepsat, zadejte jedno z DECLARE_CLASSFACTORYXXX maker v definici třídy. Například makro DECLARE_CLASSFACTORY_EX používá zadanou třídu pro továrnu tříd:

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.

Výše uvedená definice třídy určuje, že CMyClassFactory se použije jako výchozí objekt pro vytváření tříd objektu. CMyClassFactory musí odvodit a CComClassFactory přepsat CreateInstance.

ATL poskytuje tři další makra, která deklarují objekt pro vytváření tříd:

DECLARE_CLASSFACTORY2 používá CComClassFactory2, který řídí vytváření prostřednictvím licence.
DECLARE_CLASSFACTORY_AUTO_THREAD používá CComClassFactoryAutoThread, který vytváří objekty ve více apartmánech.
DECLARE_CLASSFACTORY_SINGLETON používá CComClassFactorySingleton, který vytváří jeden objekt CComObjectGlobal.

DECLARE_CLASSFACTORY_EX

Deklaruje cf , že se má jednat o objekt pro vytváření tříd.

DECLARE_CLASSFACTORY_EX( cf )

Parametry

viz
[v] Název třídy, která implementuje objekt továrny třídy.

Poznámky

Cf parametr musí být odvozen z CComClassFactory a přepsat metoduCreateInstance.

CComCoClass obsahuje DECLARE_CLASSFACTORY makro, které určuje CComClassFactory jako výchozí objekt pro vytváření tříd. Toto výchozí nastavení však přepíšete zahrnutím DECLARE_CLASSFACTORY_EX makra do definice třídy objektu.

Příklad

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

Deklaruje CComClassFactory2 jako objekt pro vytváření tříd.

DECLARE_CLASSFACTORY2( lic )

Parametry

lic
[v] Třída, která implementuje VerifyLicenseKey, GetLicenseKeya IsLicenseValid.

Poznámky

CComCoClass obsahuje DECLARE_CLASSFACTORY makro, které určuje CComClassFactory jako výchozí objekt pro vytváření tříd. Toto výchozí nastavení však přepíšete zahrnutím DECLARE_CLASSFACTORY2 makra do definice třídy objektu.

Příklad

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 – třída

Tato třída implementuje IClassFactory2 rozhraní.

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

Parametry

licence
Třída, která implementuje následující statické funkce:

static BOOL VerifyLicenseKey( BSTR bstr );
static BOOL GetLicenseKey( DWORD dwReserved, BSTR * pBstr );
static BOOL IsLicenseValid( );

Poznámky

CComClassFactory2 implementuje IClassFactory2 rozhraní, což je rozšíření IClassFactory. IClassFactory2 řídí vytváření objektů prostřednictvím licence. Objekt pro vytváření tříd spuštěný na licencovaný počítač může poskytnout licenční klíč za běhu. Tento licenční klíč umožňuje aplikaci vytvořit instanci objektů, pokud neexistuje úplná licence počítače.

Objekty ATL obvykle získávají objekt pro vytváření tříd odvozením z CComCoClass. Tato třída obsahuje DECLARE_CLASSFACTORY makra, které deklaruje CComClassFactory jako výchozí objekt pro vytváření tříd. Chcete-li použít CComClassFactory2, zadejte DECLARE_CLASSFACTORY2 makro v definici třídy objektu. Příklad:

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, parametr šablony pro CComClassFactory2, musí implementovat statické funkce VerifyLicenseKey, GetLicenseKeya IsLicenseValid. Následuje příklad jednoduché třídy licence:

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; }
};

CComClassFactory2 je odvozena z obou CComClassFactory2Base a licencí. CComClassFactory2Base, naopak je odvozen z IClassFactory2 CComObjectRootEx < CComGlobalsThreadModel >.

DECLARE_CLASSFACTORY_AUTO_THREAD

Deklaruje CComClassFactoryAutoThread jako objekt pro vytváření tříd.

DECLARE_CLASSFACTORY_AUTO_THREAD()

Poznámky

CComCoClass obsahuje DECLARE_CLASSFACTORY makro, které určuje CComClassFactory jako výchozí objekt pro vytváření tříd. Pokud ale do definice třídy objektu zahrnete DECLARE_CLASSFACTORY_AUTO_THREAD makro, přepíšete toto výchozí nastavení.

Když vytváříte objekty ve více apartmánech (na serveru typu out-of-proc), přidejte do třídy DECLARE_CLASSFACTORY_AUTO_THREAD.

Příklad

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 – třída

Tato třída implementuje IClassFactory rozhraní a umožňuje vytvářet objekty v několika apartmánech.

Důležité

Tuto třídu a její členy nelze použít v aplikacích, které se spouští v prostředí Windows Runtime.

class CComClassFactoryAutoThread : public IClassFactory,
public CComObjectRootEx<CComGlobalsThreadModel>

Poznámky

CComClassFactoryAutoThreadje podobný CComClassFactory, ale umožňuje vytváření objektů ve více apartmánech. Pokud chcete využít tuto podporu, odvodit modul EXE z CComAutoThreadModule.

Objekty ATL obvykle získávají objekt pro vytváření tříd odvozením z CComCoClass. Tato třída obsahuje DECLARE_CLASSFACTORY makra, které deklaruje CComClassFactory jako výchozí objekt pro vytváření tříd. Chcete-li použít CComClassFactoryAutoThread, zadejte DECLARE_CLASSFACTORY_AUTO_THREAD makro v definici třídy objektu. Příklad:

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

Deklaruje CComClassFactorySingleton jako objekt pro vytváření tříd.

DECLARE_CLASSFACTORY_SINGLETON( obj )

Parametry

Obj
[v] Název objektu třídy.

Poznámky

CComCoClass obsahuje DECLARE_CLASSFACTORY makro, které určuje CComClassFactory jako výchozí objekt pro vytváření tříd. Zahrnutím makra DECLARE_CLASSFACTORY_SINGLETON do definice třídy objektu však toto výchozí nastavení přepíšete.

Příklad

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 – třída

Tato třída je odvozena z CComClassFactory a používá CComObjectGlobal k vytvoření jednoho objektu.

Důležité

Tuto třídu a její členy nelze použít v aplikacích, které se spouští v prostředí Windows Runtime.

template<class T>
class CComClassFactorySingleton : public CComClassFactory

Parametry

T
Tvůj předmět.

CComClassFactorySingleton je odvozen z CComClassFactory a používá CComObjectGlobal k vytvoření jednoho objektu. Každé volání CreateInstance metody jednoduše dotazuje tento objekt pro ukazatel rozhraní.

Poznámky

Objekty ATL obvykle získávají objekt pro vytváření tříd odvozením z CComCoClass. Tato třída obsahuje DECLARE_CLASSFACTORY makra, které deklaruje CComClassFactory jako výchozí objekt pro vytváření tříd. Chcete-li použít CComClassFactorySingleton, zadejte DECLARE_CLASSFACTORY_SINGLETON makro v definici třídy objektu. Příklad:

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

Deklaruje virtuální funkci GetControllingUnknown.

DECLARE_GET_CONTROLLING_UNKNOWN()

Poznámky

Přidejte toto makro do objektu, pokud se zobrazí chybová zpráva kompilátoru, která GetControllingUnknown není definována (například v CComAggregateCreator).

DECLARE_NOT_AGGREGATABLE

Určuje, že objekt nelze agregovat.

DECLARE_NOT_AGGREGATABLE( x )

Parametry

x
[v] Název objektu třídy, který definujete jako ne agregatable.

Poznámky

DECLARE_NOT_AGGREGATABLE způsobí CreateInstance vrácení chyby (CLASS_E_NOAGGREGATION), pokud se pokusíte agregovat objekt.

CComCoClass ve výchozím nastavení obsahuje DECLARE_AGGREGATABLE makro, které určuje, že objekt lze agregovat. Chcete-li toto výchozí chování přepsat, zahrňte do definice třídy DECLARE_NOT_AGGREGATABLE.

Příklad

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

   DECLARE_NOT_AGGREGATABLE(CNoAggClass)
};

DECLARE_ONLY_AGGREGATABLE

Určuje, že objekt musí být agregován.

DECLARE_ONLY_AGGREGATABLE( x )

Parametry

x
[v] Název objektu třídy, který definujete jako pouze agregatable.

Poznámky

DECLARE_ONLY_AGGREGATABLE způsobí chybu (E_FAIL), pokud dojde k pokusu o CoCreate objekt jako neagregovaný objekt.

CComCoClass ve výchozím nastavení obsahuje DECLARE_AGGREGATABLE makro, které určuje, že objekt lze agregovat. Pokud chcete toto výchozí chování přepsat, zahrňte do definice třídy DECLARE_ONLY_AGGREGATABLE.

Příklad

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

   DECLARE_ONLY_AGGREGATABLE(COnlyAggClass)
};

DECLARE_POLY_AGGREGATABLE

Určuje, že instance CComPolyObject < x > je vytvořena při vytvoření objektu.

DECLARE_POLY_AGGREGATABLE( x )

Parametry

x
[v] Název objektu třídy, který definujete jako agregatable nebo není agregatable.

Poznámky

Při vytváření se zkontroluje hodnota vnější neznámé hodnoty. Pokud má hodnotu NULL, IUnknown implementuje se pro neagregovaný objekt. Pokud vnější neznámý není NULL, IUnknown je implementováno pro agregovaný objekt.

Výhodou použití DECLARE_POLY_AGGREGATABLE je, že se v modulu nemusíte zabývat CComAggObject CComObject agregovanými a neagregovanými případy. Jeden CComPolyObject objekt zpracovává oba případy. To znamená, že v modulu existuje jenom jedna kopie virtuální tabulky a jedna kopie funkcí. Pokud je vaše virtuální tabulka velká, může se tím podstatně zmenšit velikost modulu. Pokud je však tabulka vtable malá, může použití CComPolyObject vést k mírně větší velikosti modulu, protože není optimalizovaná pro agregovaný nebo neagregovaný objekt, jak jsou CComAggObject a CComObject.

Makro DECLARE_POLY_AGGREGATABLE se automaticky deklaruje v objektu, pokud k vytvoření úplného ovládacího prvku použijete Průvodce ovládacím prvky ATL.

DECLARE_PROTECT_FINAL_CONSTRUCT

Chrání objekt před odstraněním, pokud (během FinalConstruct) interní agregovaný objekt zvýší počet odkazů a potom sníží počet na 0.

DECLARE_PROTECT_FINAL_CONSTRUCT()

DECLARE_VIEW_STATUS

Toto makro umístěte do třídy ovládacího prvku ACTIVEX ovládacího prvku ATL, aby bylo možné určit příznaky VIEWSTATUS do kontejneru.

DECLARE_VIEW_STATUS( statusFlags )

Parametry

statusFlags
[v] Příznaky VIEWSTATUS. Seznam příznaků najdete v části VIEWSTATUS .

Příklad

DECLARE_VIEW_STATUS(VIEWSTATUS_SOLIDBKGND | VIEWSTATUS_OPAQUE)

Viz také

Makra

Sdílet prostřednictvím

Agregační makra a makra objektu pro vytváření tříd

Požadavky

DECLARE_AGGREGATABLE

Parametry

Poznámky

Příklad

DECLARE_CLASSFACTORY

Poznámky

Příklad

CComClassFactory – třída

Poznámky

DECLARE_CLASSFACTORY_EX

Parametry

Poznámky

Příklad

DECLARE_CLASSFACTORY2

Parametry

Poznámky

Příklad

CComClassFactory2 – třída

Parametry

Poznámky

DECLARE_CLASSFACTORY_AUTO_THREAD

Poznámky

Příklad

CComClassFactoryAutoThread – třída

Poznámky

DECLARE_CLASSFACTORY_SINGLETON

Parametry

Poznámky

Příklad

CComClassFactorySingleton – třída

Parametry

Poznámky

DECLARE_GET_CONTROLLING_UNKNOWN

Poznámky

DECLARE_NOT_AGGREGATABLE

Parametry

Poznámky

Příklad

DECLARE_ONLY_AGGREGATABLE

Parametry

Poznámky

Příklad

DECLARE_POLY_AGGREGATABLE

Parametry

Poznámky

DECLARE_PROTECT_FINAL_CONSTRUCT

DECLARE_VIEW_STATUS

Parametry

Příklad

Viz také

Váš názor

Další materiály