Agregação e macros de fábrica de classes
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_CLASSFACTORY2 Usa CComClassFactory2, que controla a criação por meio de uma licença.
DECLARE_CLASSFACTORY_AUTO_THREAD Usa CComClassFactoryAutoThread, que cria objetos em vários apartments.
DECLARE_CLASSFACTORY_SINGLETON Usa CComClassFactorySingleton, que constrói um único objeto CComObjectGlobal.
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
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de