Макросы агрегирования и фабрик классов

Статья
10/12/2023

Эти макросы предоставляют способы управления агрегированием и объявлением фабрик классов.

Макрос	Description
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, который создает объекты в нескольких квартирах.
DECLARE_CLASSFACTORY_SINGLETON Использует CComClassFactorySingleton, который создает один объект CComObjectGlobal.

DECLARE_CLASSFACTORY_EX

cf Объявляется фабрикой классов.

DECLARE_CLASSFACTORY_EX( cf )

Параметры

cf
[in] Имя класса, реализующего объект фабрики классов.

Замечания

Параметр 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 управляет созданием объекта с помощью лицензии. Фабрика классов, выполняемая на лицензированном компьютере, может предоставить ключ лицензии во время выполнения. Этот ключ лицензии позволяет приложению создавать экземпляры объектов, если полная лицензия компьютера не существует.

Объекты 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 в определение класса объекта, вы переопределите этот параметр по умолчанию.

При создании объектов в нескольких квартирах (на сервере вне proc) добавьте 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 и позволяет создавать объекты в нескольких квартирах.

Внимание

Этот класс и его члены нельзя использовать в приложениях, выполняемых в среде выполнения Windows.

class CComClassFactoryAutoThread : public IClassFactory,
public CComObjectRootEx<CComGlobalsThreadModel>

Замечания

CComClassFactoryAutoThread аналогичен CComClassFactory, но позволяет создавать объекты в нескольких квартирах. Чтобы воспользоваться этой поддержкой, наследуйте модуль EXE из CComAutoThreadModule.

Объекты 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] Имя объекта класса, определяемого как агрегируемое.

Замечания

DECLARE_ONLY_AGGREGATABLE вызывает ошибку (E_FAIL), если попытка выполнить попытку к CoCreate объекту в качестве негрегатированного объекта.

По умолчанию 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 может привести к немного большему размеру модуля, так как он не оптимизирован для агрегированного или негрегатированного объекта, как и CComObjectCComAggObject .

Макрос DECLARE_POLY_AGGREGATABLE автоматически объявляется в объекте, если вы используете мастер управления ATL для создания полного элемента управления.

DECLARE_PROTECT_FINAL_CONSTRUCT

Защищает объект от удаления, если (во время FinalConstruct) внутренний агрегированный объект увеличивает число ссылок, а затем уменьшает число до 0.

DECLARE_PROTECT_FINAL_CONSTRUCT()

DECLARE_VIEW_STATUS

Поместите этот макрос в класс элемента управления ActiveX ATL, чтобы указать флаги VIEWSTATUS для контейнера.

DECLARE_VIEW_STATUS( statusFlags )

Параметры

statusFlags
[in] Флаги VIEWSTATUS. Список флагов см. в VIEWSTATUS .

Пример

DECLARE_VIEW_STATUS(VIEWSTATUS_SOLIDBKGND | VIEWSTATUS_OPAQUE)

См. также

Макросы

Поделиться через

Макросы агрегирования и фабрик классов

Требования

DECLARE_AGGREGATABLE

Параметры

Замечания

Пример

DECLARE_CLASSFACTORY

Замечания

Пример

Класс CComClassFactory

Замечания

DECLARE_CLASSFACTORY_EX

Параметры

Замечания

Пример

DECLARE_CLASSFACTORY2

Параметры

Замечания

Пример

Класс CComClassFactory2

Параметры

Замечания

DECLARE_CLASSFACTORY_AUTO_THREAD

Замечания

Пример

Класс CComClassFactoryAutoThread

Замечания

DECLARE_CLASSFACTORY_SINGLETON

Параметры

Замечания

Пример

Класс CComClassFactorySingleton

Параметры

Замечания

DECLARE_GET_CONTROLLING_UNKNOWN

Замечания

DECLARE_NOT_AGGREGATABLE

Параметры

Замечания

Пример

DECLARE_ONLY_AGGREGATABLE

Параметры

Замечания

Пример

DECLARE_POLY_AGGREGATABLE

Параметры

Замечания

DECLARE_PROTECT_FINAL_CONSTRUCT

DECLARE_VIEW_STATUS

Параметры

Пример

См. также

Обратная связь

Дополнительные ресурсы