Macros de agregación y generador de clases
Estas macros proporcionan formas de controlar la agregación y de declarar generadores de clases.
| Macro | Descripción |
|---|---|
| DECLARE_AGGREGATABLE | Declara que el objeto se puede agregar (valor predeterminado). |
| DECLARE_CLASSFACTORY | Declara el generador de clases para que sea CComClassFactory, el generador de clases predeterminado de ATL. |
| DECLARE_CLASSFACTORY_EX | Declara que el objeto de generador de clases es el generador de clases. |
| DECLARE_CLASSFACTORY2 | Declara que CComClassFactory2 es el generador de clases. |
| DECLARE_CLASSFACTORY_AUTO_THREAD | Declara que CComClassFactoryAutoThread es el generador de clases. |
| DECLARE_CLASSFACTORY_SINGLETON | Declara que CComClassFactorySingleton es el generador de clases. |
| DECLARE_GET_CONTROLLING_UNKNOWN | Declara una función virtual GetControllingUnknown. |
| DECLARE_NOT_AGGREGATABLE | Declara que el objeto no se puede agregar. |
| DECLARE_ONLY_AGGREGATABLE | Declara que el objeto no se puede agregar. |
| DECLARE_POLY_AGGREGATABLE | Comprueba el valor del desconocido externo y declara si el objeto se puede agregar o no, según corresponda. |
| DECLARE_PROTECT_FINAL_CONSTRUCT | Protege el objeto externo de la eliminación durante la construcción de un objeto interno. |
| DECLARE_VIEW_STATUS | Especifica las marcas VIEWSTATUS para el contenedor. |
Requisitos
Encabezado: atlcom.h
DECLARE_AGGREGATABLE
Especifica que el objeto puede agregarse.
DECLARE_AGGREGATABLE( x )
Parámetros
x
[in] Nombre de la clase que se va a definir como agregable.
Comentarios
CComCoClass contiene esta macro para especificar el modelo de agregación predeterminado. Para invalidar este valor predeterminado, especifique la macro DECLARE_NOT_AGGREGATABLE o la macro DECLARE_ONLY_AGGREGATABLE en la definición de clase.
Ejemplo
class ATL_NO_VTABLE CNoAggClass :
public CComObjectRoot,
public CComCoClass<CNoAggClass, &CLSID_NoAggClass>
{
public:
CNoAggClass()
{
}
DECLARE_NOT_AGGREGATABLE(CNoAggClass)
};
DECLARE_CLASSFACTORY
Declara que CComClassFactory2 es el generador de clases.
DECLARE_CLASSFACTORY()
Comentarios
CComCoClass usa esta macro para declarar el generador de clases predeterminado para el objeto.
Ejemplo
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 (clase)
Esta clase implementa la interfaz IClassFactory2.
class CComClassFactory : public IClassFactory,
public CComObjectRootEx<CComGlobalsThreadModel>
Comentarios
CComClassFactory implementa la interfaz IClassFactory, que contiene métodos para crear un objeto de un CLSID determinado, así como bloquear el generador de clases en memoria para permitir que se creen nuevos objetos más rápidamente. IClassFactory debe implementarse para cada clase que registre en el Registro del sistema y a la que asigne un CLSID.
Normalmente, los objetos ATL adquieren un generador de clases al derivar de CComCoClass. Esta clase incluye la macro DECLARE_CLASSFACTORY, que declara que CComClassFactory es el generador de clases predeterminado. Para invalidar este valor predeterminado, especifique una de las macros DECLARE_CLASSFACTORYXXX en la definición de clase. Por ejemplo, la macro DECLARE_CLASSFACTORY_EX usa la clase especificada para el generador de clases:
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.
La definición de clase anterior especifica que CMyClassFactory se usará como generador de clases predeterminado del objeto. CMyClassFactory debe derivar de CComClassFactory e invalidar CreateInstance.
ATL proporciona otras tres macros que declaran un generador de clases:
DECLARE_CLASSFACTORY2 Usa CComClassFactory2, que controla la creación a través de una licencia.
DECLARE_CLASSFACTORY_AUTO_THREAD Usa CComClassFactoryAutoThread, que crea objetos en varios apartamentos.
DECLARE_CLASSFACTORY_SINGLETON Usa CComClassFactorySingleton, que construye un único objeto CComObjectGlobal.
DECLARE_CLASSFACTORY_EX
Declara cf que es el generador de clases.
DECLARE_CLASSFACTORY_EX( cf )
Parámetros
cf
[in] El nombre de la clase que implementa el objeto de generador de clases.
Comentarios
El parámetro cf debe derivar de CComClassFactory e invalidar el método CreateInstance.
CComCoClass incluye la macro DECLARE_CLASSFACTORY, que especifica CComClassFactory como generador de clases predeterminado. Sin embargo, al incluir la macro DECLARE_CLASSFACTORY_EX en la definición de clase del objeto, se invalida este valor predeterminado.
Ejemplo
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 que CComClassFactory2 es el generador de clases.
DECLARE_CLASSFACTORY2( lic )
Parámetros
lic
[in] Una clase que implementa VerifyLicenseKey, GetLicenseKey y IsLicenseValid.
Comentarios
CComCoClass incluye la macro DECLARE_CLASSFACTORY, que especifica que CComClassFactory es el generador de clases predeterminado. Sin embargo, al incluir la macro DECLARE_CLASSFACTORY2 en la definición de clase del objeto, se invalida este valor predeterminado.
Ejemplo
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
Clase CComClassFactory2
Esta clase implementa la interfaz IClassFactory2.
template <class license>
class CComClassFactory2 : public IClassFactory2,
public CComObjectRootEx<CComGlobalsThreadModel>,
public license
Parámetros
license
Una clase que implementa las siguientes funciones estáticas:
static BOOL VerifyLicenseKey( BSTR bstr );static BOOL GetLicenseKey( DWORD dwReserved, BSTR * pBstr );static BOOL IsLicenseValid( );
Comentarios
CComClassFactory2 implementa la interfaz IClassFactory2, que es una extensión de IClassFactory. IClassFactory2 controla la creación de objetos mediante una licencia. Un generador de clases que se ejecuta en una máquina con licencia puede proporcionar una clave de licencia de tiempo de ejecución. Esta clave de licencia permite que una aplicación crea instancias de objetos cuando no existe una licencia de máquina completa.
Normalmente, los objetos ATL adquieren un generador de clases al derivar de CComCoClass. Esta clase incluye la macro DECLARE_CLASSFACTORY, que declara CComClassFactory como generador de clases predeterminado. Para usar CComClassFactory2, especifique la macro DECLARE_CLASSFACTORY2 en la definición de clase del objeto. Por ejemplo:
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, el parámetro de plantilla para CComClassFactory2, debe implementar las funciones estáticas VerifyLicenseKey, GetLicenseKey y IsLicenseValid. A continuación, se muestra un ejemplo de una clase de licencia simple:
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 y de la licencia. CComClassFactory2Base, a su vez, deriva de IClassFactory2 y CComObjectRootEx< CComGlobalsThreadModel >.
DECLARE_CLASSFACTORY_AUTO_THREAD
Declara que CComClassFactoryAutoThread es el generador de clases.
DECLARE_CLASSFACTORY_AUTO_THREAD()
Comentarios
CComCoClass incluye la macro DECLARE_CLASSFACTORY, que especifica que CComClassFactory es el generador de clases predeterminado. Sin embargo, al incluir la macro DECLARE_CLASSFACTORY_EX en la definición de clase del objeto, se invalida este valor predeterminado.
Al crear objetos en varios apartamentos (en un servidor fuera de procesador), agregue DECLARE_CLASSFACTORY_AUTO_THREAD a la clase.
Ejemplo
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 (clase)
Esta clase implementa la interfaz IClassFactory y permite que se creen objetos en varios apartamentos.
Importante
Esta clase y sus miembros no se pueden usar en las aplicaciones que se ejecutan en Windows Runtime.
class CComClassFactoryAutoThread : public IClassFactory,
public CComObjectRootEx<CComGlobalsThreadModel>
Comentarios
CComClassFactoryAutoThread es similar a CComClassFactory, pero permite que se creen objetos en varios apartamentos. Para aprovechar esta compatibilidad, derive el módulo EXE de CComAutoThreadModule.
Normalmente, los objetos ATL adquieren un generador de clases al derivar de CComCoClass. Esta clase incluye la macro DECLARE_CLASSFACTORY, que declara CComClassFactory como generador de clases predeterminado. Para usar CComClassFactoryAutoThread, especifique la macro DECLARE_CLASSFACTORY_AUTO_THREAD en la definición de clase del objeto. Por ejemplo:
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 que CComClassFactorySingleton es el generador de clases.
DECLARE_CLASSFACTORY_SINGLETON( obj )
Parámetros
obj
[in] El nombre del objeto de clase.
Comentarios
CComCoClass incluye la macro DECLARE_CLASSFACTORY, que especifica que CComClassFactory es el generador de clases predeterminado. Sin embargo, al incluir la macro DECLARE_CLASSFACTORY_SINGLETON en la definición de clase del objeto, se invalida este valor predeterminado.
Ejemplo
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.
Clase CComClassFactorySingleton
Esta clase deriva de CComClassFactory y usa CComObjectGlobal para construir un solo objeto.
Importante
Esta clase y sus miembros no se pueden usar en las aplicaciones que se ejecutan en Windows Runtime.
template<class T>
class CComClassFactorySingleton : public CComClassFactory
Parámetros
T
Su clase.
CComClassFactorySingleton deriva de CComClassFactory y usa CComObjectGlobal para construir un solo objeto. Cada llamada al método CreateInstance simplemente consulta este objeto para un puntero de interfaz.
Comentarios
Normalmente, los objetos ATL adquieren un generador de clases al derivar de CComCoClass. Esta clase incluye la macro DECLARE_CLASSFACTORY, que declara que CComClassFactory es el generador de clases predeterminado. Para usar CComClassFactorySingleton, especifique la macro DECLARE_CLASSFACTORY_SINGLETON en la definición de clase del objeto. Por ejemplo:
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 una función virtual GetControllingUnknown.
DECLARE_GET_CONTROLLING_UNKNOWN()
Comentarios
Agregue esta macro al objeto si obtiene el mensaje de error del compilador que GetControllingUnknown no está definido (por ejemplo, en CComAggregateCreator).
DECLARE_NOT_AGGREGATABLE
Declara que el objeto no se puede agregar.
DECLARE_NOT_AGGREGATABLE( x )
Parámetros
x
[in] El nombre del objeto de clase que está definiendo como no agregable.
Comentarios
DECLARE_NOT_AGGREGATABLE hace que CreateInstance se devuelva un error (CLASS_E_NOAGGREGATION) si se intenta agregar al objeto.
De forma predeterminada, CComCoClass contiene la macro DECLARE_AGGREGATABLE, que especifica que el objeto se puede agregar. Para invalidar este comportamiento predeterminado, incluya DECLARE_NOT_AGGREGATABLE en la definición de clase.
Ejemplo
class ATL_NO_VTABLE CNoAggClass :
public CComObjectRoot,
public CComCoClass<CNoAggClass, &CLSID_NoAggClass>
{
public:
CNoAggClass()
{
}
DECLARE_NOT_AGGREGATABLE(CNoAggClass)
};
DECLARE_ONLY_AGGREGATABLE
Especifica que su objeto se debe agregar.
DECLARE_ONLY_AGGREGATABLE( x )
Parámetros
x
[in] El nombre del objeto de clase que está definiendo como no agregable.
Comentarios
DECLARE_ONLY_AGGREGATABLE produce un error (E_FAIL) si se realiza un intento de CoCreate el objeto como objeto no agregado.
De forma predeterminada, CComCoClass contiene la macro DECLARE_AGGREGATABLE, que especifica que el objeto se puede agregar. Para invalidar este comportamiento predeterminado, incluya DECLARE_NOT_AGGREGATABLE en la definición de clase.
Ejemplo
class ATL_NO_VTABLE COnlyAggClass :
public CComObjectRoot,
public CComCoClass<COnlyAggClass, &CLSID_OnlyAggClass>
{
public:
COnlyAggClass()
{
}
DECLARE_ONLY_AGGREGATABLE(COnlyAggClass)
};
DECLARE_POLY_AGGREGATABLE
Especifica que se crea una instancia de CComPolyObject <x> cuando se crea el objeto.
DECLARE_POLY_AGGREGATABLE( x )
Parámetros
x
[in] El nombre del objeto de clase que está definiendo como agregable o no agregable.
Comentarios
Durante la creación, se comprueba el valor del elemento desconocido externo. Si es null, IUnknown se implementa para un objeto no agregado. Si el desconocido externo no es null, IUnknown se implementa para un objeto agregado.
La ventaja de usar DECLARE_POLY_AGGREGATABLE es que evita tener tanto CComAggObject comoCComObject en el módulo para controlar los casos agregados y no agregados. Un solo objeto CComPolyObject controla ambos casos. Esto significa que solo existe una copia de la tabla virtual y una copia de las funciones existentes en el módulo. Si la tabla virtual es grande, esto puede reducir considerablemente el tamaño del módulo. Pero si la tabla virtual es pequeña, el uso de CComPolyObject puede dar lugar a un tamaño de módulo ligeramente mayor porque no está optimizado para un objeto agregado o no agregado, como sí lo están CComAggObject y CComObject.
La macro DECLARE_POLY_AGGREGATABLE se declara automáticamente en el objeto si usa el Asistente para controles ATL para crear un control total.
DECLARE_PROTECT_FINAL_CONSTRUCT
Protege al objeto de ser eliminado si (durante FinalConstruct) el objeto agregado interno incrementa el recuento de referencias y, a continuación, disminuye el recuento a 0.
DECLARE_PROTECT_FINAL_CONSTRUCT()
DECLARE_VIEW_STATUS
Coloque esta macro en la clase de control de un control ActiveX ATL para especificar las marcas VIEWSTATUS en el contenedor.
DECLARE_VIEW_STATUS( statusFlags )
Parámetros
statusFlags
[in] Las marcas VIEWSTATUS. Consulte VIEWSTATUS para obtener una lista de marcas.
Ejemplo
DECLARE_VIEW_STATUS(VIEWSTATUS_SOLIDBKGND | VIEWSTATUS_OPAQUE)
Consulte también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de