Compartilhar via


Macros de fábrica de classes e agregação

Essas macros fornecem maneiras de controlar a agregação e declarar fábricas de classes.

Macro Descrição
DECLARE_AGGREGATABLE Declara que seu objeto pode ser agregado (o padrão).
DECLARE_CLASSFACTORY Declara a fábrica de classes como CComClassFactory, a fábrica de classes padrão da ATL.
DECLARE_CLASSFACTORY_EX Declara seu objeto de fábrica de classe como a fábrica de classes.
DECLARE_CLASSFACTORY2 Declara CComClassFactory2 como a fábrica de classes.
DECLARE_CLASSFACTORY_AUTO_THREAD Declara CComClassFactoryAutoThread como a fábrica de classes.
DECLARE_CLASSFACTORY_SINGLETON Declara CComClassFactorySingleton como a fábrica de classes.
DECLARE_GET_CONTROLLING_UNKNOWN Declara uma função GetControllingUnknown virtual.
DECLARE_NOT_AGGREGATABLE Declara que seu objeto não pode ser agregado.
DECLARE_ONLY_AGGREGATABLE Declara que seu objeto deve ser agregado.
DECLARE_POLY_AGGREGATABLE Verifica o valor do desconhecido externo e declara seu objeto agregável ou não agregável, conforme apropriado.
DECLARE_PROTECT_FINAL_CONSTRUCT Protege o objeto externo contra exclusão durante a construção de um objeto interno.
DECLARE_VIEW_STATUS Especifica os sinalizadores VIEWSTATUS para o contêiner.

Requisitos

Cabeçalho: atlcom.h

DECLARE_AGGREGATABLE

Especifica que o objeto pode ser agregado.

DECLARE_AGGREGATABLE( x )

Parâmetros

x
[in] O nome da classe que você está definindo como agregável.

Comentários

CComCoClass contém essa macro para especificar o modelo de agregação padrão. Para substituir esse padrão, especifique a macro DECLARE_NOT_AGGREGATABLE ou DECLARE_ONLY_AGGREGATABLE na definição de classe.

Exemplo

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

   DECLARE_NOT_AGGREGATABLE(CNoAggClass)
};

DECLARE_CLASSFACTORY

Declara CComClassFactory2 como a fábrica de classes.

DECLARE_CLASSFACTORY()

Comentários

CComCoClass usa essa macro para declarar a fábrica de classes padrão para o objeto.

Exemplo

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

Classe CComClassFactory

Essa classe implementa a interface IClassFactory.

class CComClassFactory : public IClassFactory,
public CComObjectRootEx<CComGlobalsThreadModel>

Comentários

CComClassFactory implementa a interface IClassFactory, que contém métodos para criar um objeto de um CLSID específico, bem como bloquear a fábrica de classes na memória para permitir que novos objetos sejam criados mais rapidamente. IClassFactory deve ser implementado para cada classe que você registrar no registro do sistema e para a qual você atribui um CLSID.

Objetos ATL normalmente adquirem uma fábrica de classes derivando de CComCoClass. Essa classe inclui a macro DECLARE_CLASSFACTORY, que declara CComClassFactory como a fábrica de classes padrão. Para substituir esse padrão, especifique uma das macros DECLARE_CLASSFACTORYXXX em sua definição de classe. Por exemplo, a macro DECLARE_CLASSFACTORY_EX usa a classe especificada para a fábrica de classes:

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.

A definição de classe acima especifica que CMyClassFactory será usada como a fábrica de classes padrão do objeto. CMyClassFactory deve derivar de CComClassFactory e substituir CreateInstance.

A ATL fornece três outras macros que declaram uma fábrica de classes:

DECLARE_CLASSFACTORY_EX

Declara cf como a fábrica de classes.

DECLARE_CLASSFACTORY_EX( cf )

Parâmetros

cf
[in] O nome da classe que implementa o objeto de fábrica de classes.

Comentários

O parâmetro cf deve derivar de CComClassFactory e substituir o método CreateInstance.

CComCoClass inclui a macro DECLARE_CLASSFACTORY, que especifica CComClassFactory como a fábrica de classes padrão. No entanto, ao incluir a macro DECLARE_CLASSFACTORY_EX na definição de classe do objeto, você substituirá esse padrão.

Exemplo

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

Declara CComClassFactory2 como a fábrica de classes.

DECLARE_CLASSFACTORY2( lic )

Parâmetros

lic
[in] Uma classe que implementa VerifyLicenseKey, GetLicenseKey e IsLicenseValid.

Comentários

CComCoClass inclui a macro DECLARE_CLASSFACTORY, que especifica CComClassFactory como a fábrica de classes padrão. No entanto, ao incluir a macro DECLARE_CLASSFACTORY2 na definição de classe do objeto, você substituirá esse padrão.

Exemplo

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

Classe CComClassFactory2

Essa classe implementa a interface IClassFactory2.

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

Parâmetros

license
Uma classe que implementa as seguintes funções estáticas:

  • static BOOL VerifyLicenseKey( BSTR bstr );

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

  • static BOOL IsLicenseValid( );

Comentários

CComClassFactory2 implementa a interface IClassFactory2, que é uma extensão de IClassFactory. IClassFactory2 controla a criação de objeto por meio de uma licença. Uma fábrica de classes em execução em um computador licenciado pode fornecer uma chave de licença em tempo de execução. Essa chave de licença permite que um aplicativo crie uma instância de objetos quando uma licença completa do computador não existe.

Objetos ATL normalmente adquirem uma fábrica de classes derivando de CComCoClass. Essa classe inclui a macro DECLARE_CLASSFACTORY, que declara CComClassFactory como a fábrica de classes padrão. Para usar CComClassFactory2, especifique a macro DECLARE_CLASSFACTORY2 na definição de classe do seu objeto. Por exemplo:

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, o parâmetro de modelo para CComClassFactory2, deve implementar as funções estáticas VerifyLicenseKey, GetLicenseKey e IsLicenseValid. O exemplo a seguir é de uma classe de licença simples:

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 deriva de CComClassFactory2Base e license. CComClassFactory2Base, por sua vez, deriva de IClassFactory2 e CComObjectRootEx< CComGlobalsThreadModel >.

DECLARE_CLASSFACTORY_AUTO_THREAD

Declara CComClassFactoryAutoThread como a fábrica de classes.

DECLARE_CLASSFACTORY_AUTO_THREAD()

Comentários

CComCoClass inclui a macro DECLARE_CLASSFACTORY, que especifica CComClassFactory como a fábrica de classes padrão. No entanto, ao incluir a macro DECLARE_CLASSFACTORY_AUTO_THREAD na definição de classe do objeto, você substituirá esse padrão.

Ao criar objetos em vários apartaments (em um servidor fora do proc), adicione DECLARE_CLASSFACTORY_AUTO_THREAD à sua classe.

Exemplo

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.

Classe CComClassFactoryAutoThread

Essa classe implementa a interface IClassFactory e permite que objetos sejam criados em vários apartamentos.

Importante

Essa classe e os respectivos membros não podem ser usados em aplicativos executados no Windows Runtime.

class CComClassFactoryAutoThread : public IClassFactory,
public CComObjectRootEx<CComGlobalsThreadModel>

Comentários

CComClassFactoryAutoThread é semelhante a CComClassFactory, mas permite que objetos sejam criados em vários apartamentos. Para aproveitar esse suporte, derive seu módulo EXE de CComAutoThreadModule.

Objetos ATL normalmente adquirem uma fábrica de classes derivando de CComCoClass. Essa classe inclui a macro DECLARE_CLASSFACTORY, que declara CComClassFactory como a fábrica de classes padrão. Para usar CComClassFactoryAutoThread, especifique a macro DECLARE_CLASSFACTORY_AUTO_THREAD na definição de classe do seu objeto. Por exemplo:

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

Declara CComClassFactorySingleton como a fábrica de classes.

DECLARE_CLASSFACTORY_SINGLETON( obj )

Parâmetros

obj
[in] O nome do objeto de classe.

Comentários

CComCoClass inclui a macro DECLARE_CLASSFACTORY, que especifica CComClassFactory como a fábrica de classes padrão. No entanto, ao incluir a macro DECLARE_CLASSFACTORY_SINGLETON na definição de classe do objeto, você substituirá esse padrão.

Exemplo

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 Class

Essa classe deriva de CComClassFactory e usa CComObjectGlobal para construir um único objeto.

Importante

Essa classe e os respectivos membros não podem ser usados em aplicativos executados no Windows Runtime.

template<class T>
class CComClassFactorySingleton : public CComClassFactory

Parâmetros

T
Sua classe.

CComClassFactorySingleton deriva de CComClassFactory e usa CComObjectGlobal para construir um único objeto. Cada chamada para o método CreateInstance consulta esse objeto para obter um ponteiro de interface.

Comentários

Objetos ATL normalmente adquirem uma fábrica de classes derivando de CComCoClass. Essa classe inclui a macro DECLARE_CLASSFACTORY, que declara CComClassFactory como a fábrica de classes padrão. Para usar CComClassFactorySingleton, especifique a macro DECLARE_CLASSFACTORY_SINGLETON na definição de classe do seu objeto. Por exemplo:

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

Declara uma função GetControllingUnknown virtual.

DECLARE_GET_CONTROLLING_UNKNOWN()

Comentários

Adicione essa macro ao seu objeto se você recebe a mensagem de erro do compilador de que GetControllingUnknown está indefinida (por exemplo, em CComAggregateCreator).

DECLARE_NOT_AGGREGATABLE

Especifica que seu objeto não pode ser agregado.

DECLARE_NOT_AGGREGATABLE( x )

Parâmetros

x
[in] O nome do objeto de classe que você está definindo como não agregável.

Comentários

DECLARE_NOT_AGGREGATABLE fará com que CreateInstance retorne um erro (CLASS_E_NOAGGREGATION) se for feita uma tentativa de agregação em seu objeto.

Por padrão, CComCoClass contém a macro DECLARE_AGGREGATABLE, que especifica que seu objeto pode ser agregado. Para substituir esse comportamento padrão, inclua DECLARE_NOT_AGGREGATABLE na definição de classe.

Exemplo

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

   DECLARE_NOT_AGGREGATABLE(CNoAggClass)
};

DECLARE_ONLY_AGGREGATABLE

Especifica que seu objeto deve ser agregado.

DECLARE_ONLY_AGGREGATABLE( x )

Parâmetros

x
[in] O nome do objeto de classe que você está definindo como somente agregável.

Comentários

DECLARE_ONLY_AGGREGATABLE causará um erro (E_FAIL) se uma tentativa for feita ao objeto CoCreate como objeto não agregado.

Por padrão, CComCoClass contém a macro DECLARE_AGGREGATABLE, que especifica que seu objeto pode ser agregado. Para substituir esse comportamento padrão, inclua DECLARE_ONLY_AGGREGATABLE na definição de classe.

Exemplo

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

   DECLARE_ONLY_AGGREGATABLE(COnlyAggClass)
};

DECLARE_POLY_AGGREGATABLE

Especifica que uma instância de CComPolyObject < x > é criada quando o objeto é criado.

DECLARE_POLY_AGGREGATABLE( x )

Parâmetros

x
[in] O nome do objeto de classe que você está definindo como agregável ou não agregável.

Comentários

Durante a criação, o valor do desconhecido externo é verificado. Se for NULL, IUnknown será implementado para um objeto não agregado. Se o desconhecido externo não for NULL, IUnknown será implementado para um objeto agregado.

A vantagem de usar DECLARE_POLY_AGGREGATABLE é que você evita ter CComAggObject e CComObject em seu módulo para lidar com os casos agregados e não agregados. Um único objeto CComPolyObject manipula os dois casos. Isso significa que apenas uma cópia da vtable e uma cópia das funções existem em seu módulo. Se a vtable for grande, isso poderá diminuir substancialmente o tamanho do módulo. No entanto, se a vtable for pequena, usar CComPolyObject poderá resultar em um tamanho de módulo um pouco maior porque ele não é otimizado para um objeto agregado ou não agregado, como são CComAggObject e CComObject.

A macro DECLARE_POLY_AGGREGATABLE será declarada automaticamente em seu objeto se você usar o Assistente de controle da ATL para criar um controle completo.

DECLARE_PROTECT_FINAL_CONSTRUCT

Protege o objeto de ser excluído se (durante FinalConstruct) o objeto agregado interno incrementar a contagem de referência e, em seguida, diminuir a contagem para 0.

DECLARE_PROTECT_FINAL_CONSTRUCT()

DECLARE_VIEW_STATUS

Coloque essa macro na classe de controle de um controle ActiveX da ATL para especificar os sinalizadores VIEWSTATUS para o contêiner.

DECLARE_VIEW_STATUS( statusFlags )

Parâmetros

statusFlags
[in] Os sinalizadores VIEWSTATUS. Consulte VIEWSTATUS para obter uma lista de sinalizadores.

Exemplo

DECLARE_VIEW_STATUS(VIEWSTATUS_SOLIDBKGND | VIEWSTATUS_OPAQUE)

Confira também

Macros