彙總和 Class Factory 巨集

發行項
08/03/2024

這些宏提供控制匯總和宣告類別處理站的方法。

Macro	描述
DECLARE_AGGREGATABLE	宣告可以匯總您的物件（預設值）。
DECLARE_CLASSFACTORY	將類別處理站宣告為 CComClassFactory，這是 ATL 預設類別處理站。
DECLARE_CLASSFACTORY_EX	將類別處理站物件宣告為類別處理站。
DECLARE_CLASSFACTORY2	將 CComClassFactory2 宣告為類別處理站。
DECLARE_CLASSFACTORY_AUTO_THREAD	將 CComClassFactoryAutoThread 宣告為類別處理站。
DECLARE_CLASSFACTORY_SINGLETON	將 CComClassFactorySingleton 宣告為類別處理站。
DECLARE_GET_CONTROLLING_UNKNOWN	宣告虛擬 `GetControllingUnknown` 函式。
DECLARE_NOT_AGGREGATABLE	宣告無法匯總您的物件。
DECLARE_ONLY_AGGREGATABLE	宣告您的對象必須匯總。
DECLARE_POLY_AGGREGATABLE	檢查外部未知的值，並視需要宣告您的物件可匯總或不可匯總。
DECLARE_PROTECT_FINAL_CONSTRUCT	保護外部對象在內部物件的建構期間刪除。
DECLARE_VIEW_STATUS	指定容器的 VIEWSTATUS 旗標。

需求

標頭： atlcom.h

DECLARE_AGGREGATABLE

指定可以匯總您的物件。

DECLARE_AGGREGATABLE( x )

參數

x
[in]您要定義為可匯總的類別名稱。

備註

CComCoClass 包含此巨集來指定預設匯總模型。若要覆寫此預設值，請在類別定義中指定 DECLARE_NOT_AGGREGATABLE 或 DECLARE_ONLY_AGGREGATABLE 巨集。

範例

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

   DECLARE_NOT_AGGREGATABLE(CNoAggClass)
};

DECLARE_CLASSFACTORY

將 CComClassFactory 宣告為類別處理站。

DECLARE_CLASSFACTORY()

備註

CComCoClass 會使用此巨集來宣告對象的預設類別處理站。

範例

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 類別

這個類別會實作 IClassFactory 介面。

class CComClassFactory : public IClassFactory,
public CComObjectRootEx<CComGlobalsThreadModel>

備註

CComClassFactory 會實作 IClassFactory 介面，其中包含建立特定 CLSID 物件的方法，以及鎖定記憶體中的類別處理站，以更快速地建立新的物件。 IClassFactory 必須針對您在系統登錄中註冊且指派 CLSID 的每個類別實作。

ATL 物件通常藉由衍生自 CComCoClass 來取得類別處理站。這個類別包含巨集 DECLARE_CLASSFACTORY，它會宣告 CComClassFactory 為預設類別處理站。若要覆寫此預設值，請在類別定義中指定其中一個DECLARE_CLASSFACTORYXXX 宏。例如， DECLARE_CLASSFACTORY_EX巨集使用類別處理站的指定類別：

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.

上述類別定義會 CMyClassFactory 指定將做為對象的預設類別處理站。 CMyClassFactory 必須衍生自 CComClassFactory 並覆寫 CreateInstance。

ATL 提供另外三個宣告類別處理站的宏：

DECLARE_CLASSFACTORY2使用 CComClassFactory2，控制透過授權建立。
DECLARE_CLASSFACTORY_AUTO_THREAD使用 CComClassFactoryAutoThread，這會在多個 Apartment 中建立物件。
DECLARE_CLASSFACTORY_SINGLETON使用 CComClassFactorySingleton，它會建構單一 CComObjectGlobal 物件。

DECLARE_CLASSFACTORY_EX

cf宣告為類別處理站。

DECLARE_CLASSFACTORY_EX( cf )

參數

cf
[in]實作類別 Factory 物件的類別名稱。

備註

cf 參數必須衍生自 CComClassFactory 並覆寫 CreateInstance 方法。

CComCoClass 包含 DECLARE_CLASSFACTORY 巨集，指定 CComClassFactory 為預設類別處理站。不過，藉由在對象的類別定義中包含DECLARE_CLASSFACTORY_EX 巨集，即可覆寫此預設值。

範例

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

將 CComClassFactory2 宣告為類別處理站。

DECLARE_CLASSFACTORY2( lic )

參數

lic
[in]實作 VerifyLicenseKey、 GetLicenseKey和 IsLicenseValid的類別。

備註

CComCoClass 包含 DECLARE_CLASSFACTORY巨集，它會指定 CComClassFactory 做為預設類別處理站。不過，藉由在對象的類別定義中包含DECLARE_CLASSFACTORY2 巨集，即可覆寫此預設值。

範例

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 類別

這個類別會實作 IClassFactory2 介面。

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

參數

許可證
實作下列靜態函式的類別：

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

備註

CComClassFactory2會實作 IClassFactory2 介面，這是 IClassFactory 的延伸模組。 IClassFactory2 控制透過授權建立物件。在授權電腦上執行的 Class Factory 可以提供運行時間授權密鑰。此授權金鑰可讓應用程式在完整計算機授權不存在時具現化物件。

ATL 物件通常藉由衍生自 CComCoClass 來取得類別處理站。此類別包含巨集 DECLARE_CLASSFACTORY，它會將 CComClassFactory 宣告為預設類別處理站。若要使用 CComClassFactory2，請在對象的類別定義中指定DECLARE_CLASSFACTORY2 巨集。例如：

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，對的樣板參數 CComClassFactory2必須實作靜態函式 VerifyLicenseKey、 GetLicenseKey和 IsLicenseValid。以下是簡單授權類別的範例：

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 衍生自 CComClassFactory2Base 和授權。 CComClassFactory2Base接著，衍生自 IClassFactory2 和 CComObjectRootEx< CComGlobalsThreadModel >。

DECLARE_CLASSFACTORY_AUTO_THREAD

將 CComClassFactoryAutoThread 宣告為類別處理站。

DECLARE_CLASSFACTORY_AUTO_THREAD()

備註

CComCoClass 包含 DECLARE_CLASSFACTORY巨集，它會指定 CComClassFactory 做為預設類別處理站。不過，藉由在對象的類別定義中包含DECLARE_CLASSFACTORY_AUTO_THREAD 巨集，即可覆寫此預設值。

當您在多個 Apartment 中建立物件時（在跨程式伺服器中），請將DECLARE_CLASSFACTORY_AUTO_THREAD新增至您的類別。

範例

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 類別

這個類別會實作 IClassFactory 介面，並允許在多個 Apartment 中建立物件。

重要

這個類別及其成員不能用於在 Windows 執行階段中執行的應用程式。

class CComClassFactoryAutoThread : public IClassFactory,
public CComObjectRootEx<CComGlobalsThreadModel>

備註

CComClassFactoryAutoThread 類似於 CComClassFactory，但允許在多個 Apartment 中建立物件。若要利用這項支援，請從 CComAutoThreadModule 衍生 EXE 模組。

ATL 物件通常藉由衍生自 CComCoClass 來取得類別處理站。此類別包含巨集 DECLARE_CLASSFACTORY，它會將 CComClassFactory 宣告為預設類別處理站。若要使用 CComClassFactoryAutoThread，請在對象的類別定義中指定DECLARE_CLASSFACTORY_AUTO_THREAD 巨集。例如：

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

將 CComClassFactorySingleton 宣告為類別處理站。

DECLARE_CLASSFACTORY_SINGLETON( obj )

參數

obj
[in]類別物件的名稱。

備註

CComCoClass 包含 DECLARE_CLASSFACTORY巨集，它會指定 CComClassFactory 做為預設類別處理站。不過，藉由在對象的類別定義中包含DECLARE_CLASSFACTORY_SINGLETON 巨集，即可覆寫此預設值。

範例

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 類別

這個類別衍生自 CComClassFactory ，並使用 CComObjectGlobal 建構單一物件。

重要

這個類別及其成員不能用於在 Windows 執行階段中執行的應用程式。

template<class T>
class CComClassFactorySingleton : public CComClassFactory

參數

T
您的類別。

CComClassFactorySingleton 衍生自 CComClassFactory ，並使用 CComObjectGlobal 建構單一物件。每次呼叫 CreateInstance 方法時，只要查詢這個物件是否有介面指標。

備註

ATL 物件通常藉由衍生自 CComCoClass 來取得類別處理站。這個類別包含巨集 DECLARE_CLASSFACTORY，它會宣告 CComClassFactory 為預設類別處理站。若要使用 CComClassFactorySingleton，請在對象的類別定義中指定DECLARE_CLASSFACTORY_SINGLETON 巨集。例如：

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

宣告虛擬函式 GetControllingUnknown。

DECLARE_GET_CONTROLLING_UNKNOWN()

備註

如果您收到未定義的編譯程式錯誤訊息 GetControllingUnknown ，請將此巨集新增至物件（例如，在中 CComAggregateCreator）。

DECLARE_NOT_AGGREGATABLE

指定無法匯總物件。

DECLARE_NOT_AGGREGATABLE( x )

參數

x
[in]您定義為不可匯總的類別物件名稱。

備註

如果嘗試匯總到您的物件，DECLARE_NOT_AGGREGATABLE會導致 CreateInstance 傳回錯誤（CLASS_E_NOAGGREGATION）。

根據預設， CComCoClass 包含 DECLARE_AGGREGATABLE 巨集，指定可以匯總您的物件。若要覆寫此預設行為，請在類別定義中包含DECLARE_NOT_AGGREGATABLE。

範例

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

   DECLARE_NOT_AGGREGATABLE(CNoAggClass)
};

DECLARE_ONLY_AGGREGATABLE

指定必須匯總您的物件。

DECLARE_ONLY_AGGREGATABLE( x )

參數

x
[in]您定義為只能匯總的類別物件名稱。

備註

如果嘗試以非匯總物件的形式對 CoCreate 對對象進行嘗試，DECLARE_ONLY_AGGREGATABLE會導致錯誤（E_FAIL）。

根據預設， CComCoClass 包含 DECLARE_AGGREGATABLE 巨集，指定可以匯總您的物件。若要覆寫此預設行為，請在類別定義中包含DECLARE_ONLY_AGGREGATABLE。

範例

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

   DECLARE_ONLY_AGGREGATABLE(COnlyAggClass)
};

DECLARE_POLY_AGGREGATABLE

指定建立物件時，會建立 CComPolyObject < x > 的實例。

DECLARE_POLY_AGGREGATABLE( x )

參數

x
[in]您要定義為可匯總或不可匯總的類別物件名稱。

備註

在建立期間，會檢查外部未知的值。如果是 NULL， IUnknown 則會針對非匯總物件實作。如果外部未知不是 NULL， IUnknown 則會針對匯總物件實作。

使用DECLARE_POLY_AGGREGATABLE的優點是，您避免在 CComAggObject 模組中有和 CComObject 來處理匯總和非匯總案例。單 CComPolyObject 一物件會處理這兩種情況。這表示只有一份 vtable 和一份函式存在於您的模組中。如果您的 vtable 很大，這可能會大幅減少模組大小。不過，如果您的 vtable 很小，使用 CComPolyObject 可能會導致模組大小略大，因為它未針對匯總或非匯總的對象進行優化，如同 CComAggObject 和 CComObject。

如果您使用 ATL 控件精靈來建立完整控件，則會自動在物件中宣告DECLARE_POLY_AGGREGATABLE 巨集。

DECLARE_PROTECT_FINAL_CONSTRUCT

如果（在 FinalConstruct 期間）內部匯總物件遞增參考計數，則保護物件免於遭到刪除，然後將計數遞減為 0。

DECLARE_PROTECT_FINAL_CONSTRUCT()

DECLARE_VIEW_STATUS

將此巨集放在ATL ActiveX控件的控件類別中，以指定容器的 VIEWSTATUS 旗標。

DECLARE_VIEW_STATUS( statusFlags )

參數

statusFlags
[in]VIEWSTATUS 旗標。如需旗標清單，請參閱 VIEWSTATUS 。

範例

DECLARE_VIEW_STATUS(VIEWSTATUS_SOLIDBKGND | VIEWSTATUS_OPAQUE)

另請參閱

巨集

共用方式為