Compartir a través de

Macros de agregación y generador de clases

  • Artículo

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_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)

Vea también

Macros