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. |
Cabeçalho: atlcom.h
Especifica que o objeto pode ser agregado.
DECLARE_AGGREGATABLE( x )
x
[in] O nome da classe que você está definindo como agregável.
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.
class ATL_NO_VTABLE CNoAggClass :
public CComObjectRoot,
public CComCoClass<CNoAggClass, &CLSID_NoAggClass>
{
public:
CNoAggClass()
{
}
DECLARE_NOT_AGGREGATABLE(CNoAggClass)
};
Declara CComClassFactory2 como a fábrica de classes.
DECLARE_CLASSFACTORY()
CComCoClass usa essa macro para declarar a fábrica de classes padrão para o objeto.
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
Essa classe implementa a interface IClassFactory.
class CComClassFactory : public IClassFactory,
public CComObjectRootEx<CComGlobalsThreadModel>
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.
Declara cf
como a fábrica de classes.
DECLARE_CLASSFACTORY_EX( cf )
cf
[in] O nome da classe que implementa o objeto de fábrica de classes.
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.
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.
Declara CComClassFactory2 como a fábrica de classes.
DECLARE_CLASSFACTORY2( lic )
lic
[in] Uma classe que implementa VerifyLicenseKey
, GetLicenseKey
e IsLicenseValid
.
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.
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
Essa classe implementa a interface IClassFactory2.
template <class license>
class CComClassFactory2 : public IClassFactory2,
public CComObjectRootEx<CComGlobalsThreadModel>,
public license
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( );
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 >.
Declara CComClassFactoryAutoThread como a fábrica de classes.
DECLARE_CLASSFACTORY_AUTO_THREAD()
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.
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.
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>
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.
Declara CComClassFactorySingleton como a fábrica de classes.
DECLARE_CLASSFACTORY_SINGLETON( obj )
obj
[in] O nome do objeto de classe.
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.
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.
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
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.
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.
Declara uma função GetControllingUnknown
virtual.
DECLARE_GET_CONTROLLING_UNKNOWN()
Adicione essa macro ao seu objeto se você recebe a mensagem de erro do compilador de que GetControllingUnknown
está indefinida (por exemplo, em CComAggregateCreator
).
Especifica que seu objeto não pode ser agregado.
DECLARE_NOT_AGGREGATABLE( x )
x
[in] O nome do objeto de classe que você está definindo como não agregável.
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.
class ATL_NO_VTABLE CNoAggClass :
public CComObjectRoot,
public CComCoClass<CNoAggClass, &CLSID_NoAggClass>
{
public:
CNoAggClass()
{
}
DECLARE_NOT_AGGREGATABLE(CNoAggClass)
};
Especifica que seu objeto deve ser agregado.
DECLARE_ONLY_AGGREGATABLE( x )
x
[in] O nome do objeto de classe que você está definindo como somente agregável.
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.
class ATL_NO_VTABLE COnlyAggClass :
public CComObjectRoot,
public CComCoClass<COnlyAggClass, &CLSID_OnlyAggClass>
{
public:
COnlyAggClass()
{
}
DECLARE_ONLY_AGGREGATABLE(COnlyAggClass)
};
Especifica que uma instância de CComPolyObject < x > é criada quando o objeto é criado.
DECLARE_POLY_AGGREGATABLE( x )
x
[in] O nome do objeto de classe que você está definindo como agregável ou não agregável.
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.
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()
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 )
statusFlags
[in] Os sinalizadores VIEWSTATUS. Consulte VIEWSTATUS para obter uma lista de sinalizadores.
DECLARE_VIEW_STATUS(VIEWSTATUS_SOLIDBKGND | VIEWSTATUS_OPAQUE)