Macro di aggregazione e class factory

Queste macro offrono modi per controllare l'aggregazione e dichiarare le class factory.

Requisiti

Intestazione: atlcom.h

DECLARE_AGGREGATABLE

Specifica che l'oggetto può essere aggregato.

DECLARE_AGGREGATABLE( x )

Parametri

x
[in] Nome della classe che si definisce come aggregabile.

Osservazioni:

CComCoClass contiene questa macro per specificare il modello di aggregazione predefinito. Per eseguire l'override di questa impostazione predefinita, specificare la macro DECLARE_NOT_AGGREGATABLE o DECLARE_ONLY_AGGREGATABLE nella definizione della classe.

Esempio

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

   DECLARE_NOT_AGGREGATABLE(CNoAggClass)
};

DECLARE_CLASSFACTORY

Dichiara CComClassFactory come class factory.

DECLARE_CLASSFACTORY()

Osservazioni:

CComCoClass usa questa macro per dichiarare la class factory predefinita per l'oggetto.

Esempio

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

Questa classe implementa l'interfaccia IClassFactory .

class CComClassFactory : public IClassFactory,
public CComObjectRootEx<CComGlobalsThreadModel>

Osservazioni:

CComClassFactory implementa l'interfaccia IClassFactory , che contiene metodi per la creazione di un oggetto di un particolare CLSID, nonché il blocco della class factory in memoria per consentire la creazione di nuovi oggetti più rapidamente. IClassFactory deve essere implementato per ogni classe registrata nel Registro di sistema e a cui si assegna un CLSID.

Gli oggetti ATL acquisiscono normalmente una class factory derivando da CComCoClass. Questa classe include la macro DECLARE_CLASSFACTORY, che dichiara CComClassFactory come class factory predefinita. Per eseguire l'override di questa impostazione predefinita, specificare una delle macro DECLARE_CLASSFACTORYXXX nella definizione della classe. Ad esempio, la macro DECLARE_CLASSFACTORY_EX usa la classe specificata per la class factory:

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 definizione della classe precedente specifica che CMyClassFactory verrà usata come class factory predefinita dell'oggetto. CMyClassFactory deve derivare da CComClassFactory ed eseguire l'override CreateInstancedi .

ATL fornisce altre tre macro che dichiarano una class factory:

• DECLARE_CLASSFACTORY2 Usa CComClassFactory2, che controlla la creazione tramite una licenza.

• DECLARE_CLASSFACTORY_AUTO_THREAD usa CComClassFactoryAutoThread, che crea oggetti in più appartamenti.

• DECLARE_CLASSFACTORY_SINGLETON Usa CComClassFactorySingleton, che costruisce un singolo oggetto CComObjectGlobal.

DECLARE_CLASSFACTORY_EX

cf Dichiara di essere la class factory.

DECLARE_CLASSFACTORY_EX( cf )

Parametri

cfr
[in] Nome della classe che implementa l'oggetto class factory.

Osservazioni:

Il parametro cf deve derivare da CComClassFactory ed eseguire l'override del CreateInstance metodo .

CComCoClass include la macro DECLARE_CLASSFACTORY , che specifica CComClassFactory come class factory predefinita. Tuttavia, includendo la macro DECLARE_CLASSFACTORY_EX nella definizione della classe dell'oggetto, si esegue l'override di questa impostazione predefinita.

Esempio

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

Dichiara CComClassFactory2 come class factory.

DECLARE_CLASSFACTORY2( lic )

Parametri

lic
[in] Classe che implementa VerifyLicenseKey, GetLicenseKeye IsLicenseValid.

Osservazioni:

CComCoClass include la macro DECLARE_CLASSFACTORY , che specifica CComClassFactory come factory di classi predefinita. Tuttavia, includendo la macro DECLARE_CLASSFACTORY2 nella definizione della classe dell'oggetto, si esegue l'override di questa impostazione predefinita.

Esempio

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

Questa classe implementa l'interfaccia IClassFactory2 .

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

Parametri

license
Classe che implementa le funzioni statiche seguenti:

• static BOOL VerifyLicenseKey( BSTR bstr );

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

• static BOOL IsLicenseValid( );

Osservazioni:

CComClassFactory2 implementa l'interfaccia IClassFactory2 , che è un'estensione di IClassFactory. IClassFactory2 controlla la creazione di oggetti tramite una licenza. Una class factory in esecuzione in un computer con licenza può fornire un codice di licenza in fase di esecuzione. Questo codice di licenza consente a un'applicazione di creare un'istanza di oggetti quando non esiste una licenza completa del computer.

Gli oggetti ATL acquisiscono normalmente una class factory derivando da CComCoClass. Questa classe include la macro DECLARE_CLASSFACTORY, che dichiara CComClassFactory come class factory predefinita. Per usare CComClassFactory2, specificare la macro DECLARE_CLASSFACTORY2 nella definizione della classe dell'oggetto. Ad esempio:

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, il parametro del modello in CComClassFactory2, deve implementare le funzioni VerifyLicenseKeystatiche , GetLicenseKeye IsLicenseValid. Di seguito è riportato un esempio di classe di licenza semplice:

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; }
};

CComClassFactory2deriva da entrambe CComClassFactory2Base le licenze e . CComClassFactory2Base, a sua volta, deriva da IClassFactory2 e CComObjectRootEx< CComGlobalsThreadModel >.

DECLARE_CLASSFACTORY_AUTO_THREAD

Dichiara CComClassFactoryAutoThread come class factory.

DECLARE_CLASSFACTORY_AUTO_THREAD()

Osservazioni:

CComCoClass include la macro DECLARE_CLASSFACTORY , che specifica CComClassFactory come factory di classi predefinita. Tuttavia, includendo la macro DECLARE_CLASSFACTORY_AUTO_THREAD nella definizione della classe dell'oggetto, si esegue l'override di questa impostazione predefinita.

Quando si creano oggetti in più appartamenti (in un server out-of-proc), aggiungere DECLARE_CLASSFACTORY_AUTO_THREAD alla classe.

Esempio

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

Questa classe implementa l'interfaccia IClassFactory e consente la creazione di oggetti in più appartamenti.

class CComClassFactoryAutoThread : public IClassFactory,
public CComObjectRootEx<CComGlobalsThreadModel>

Osservazioni:

CComClassFactoryAutoThread è simile a CComClassFactory, ma consente la creazione di oggetti in più appartamenti. Per sfruttare questo supporto, derivare il modulo EXE da CComAutoThreadModule.

Gli oggetti ATL acquisiscono normalmente una class factory derivando da CComCoClass. Questa classe include la macro DECLARE_CLASSFACTORY, che dichiara CComClassFactory come class factory predefinita. Per usare CComClassFactoryAutoThread, specificare la macro DECLARE_CLASSFACTORY_AUTO_THREAD nella definizione della classe dell'oggetto. Ad esempio:

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

Dichiara CComClassFactorySingleton come class factory.

DECLARE_CLASSFACTORY_SINGLETON( obj )

Parametri

obj
[in] Nome dell'oggetto classe.

Osservazioni:

CComCoClass include la macro DECLARE_CLASSFACTORY , che specifica CComClassFactory come factory di classi predefinita. Tuttavia, includendo la macro DECLARE_CLASSFACTORY_SINGLETON nella definizione della classe dell'oggetto, si esegue l'override di questa impostazione predefinita.

Esempio

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.

Classe CComClassFactorySingleton

Questa classe deriva da CComClassFactory e usa CComObjectGlobal per costruire un singolo oggetto.

template<class T>
class CComClassFactorySingleton : public CComClassFactory

Parametri

T
La tua classe.

CComClassFactorySingleton deriva da CComClassFactory e usa CComObjectGlobal per costruire un singolo oggetto. Ogni chiamata al CreateInstance metodo esegue semplicemente una query su questo oggetto per un puntatore di interfaccia.

Osservazioni:

Gli oggetti ATL acquisiscono normalmente una class factory derivando da CComCoClass. Questa classe include la macro DECLARE_CLASSFACTORY, che dichiara CComClassFactory come class factory predefinita. Per usare CComClassFactorySingleton, specificare la macro DECLARE_CLASSFACTORY_SINGLETON nella definizione della classe dell'oggetto. Ad esempio:

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

Dichiara una funzione GetControllingUnknownvirtuale .

DECLARE_GET_CONTROLLING_UNKNOWN()

Osservazioni:

Aggiungere questa macro all'oggetto se viene visualizzato il messaggio GetControllingUnknown di errore del compilatore non definito, ad esempio in CComAggregateCreator.

DECLARE_NOT_AGGREGATABLE

Specifica che l'oggetto non può essere aggregato.

DECLARE_NOT_AGGREGATABLE( x )

Parametri

x
[in] Nome dell'oggetto classe che si definisce come non aggregabile.

Osservazioni:

DECLARE_NOT_AGGREGATABLE causa CreateInstance la restituzione di un errore (CLASS_E_NOAGGREGATION) se viene effettuato un tentativo di aggregazione nell'oggetto.

Per impostazione predefinita, CComCoClass contiene la macro DECLARE_AGGREGATABLE , che specifica che l'oggetto può essere aggregato. Per eseguire l'override di questo comportamento predefinito, includere DECLARE_NOT_AGGREGATABLE nella definizione della classe.

Esempio

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

   DECLARE_NOT_AGGREGATABLE(CNoAggClass)
};

DECLARE_ONLY_AGGREGATABLE

Specifica che l'oggetto deve essere aggregato.

DECLARE_ONLY_AGGREGATABLE( x )

Parametri

x
[in] Nome dell'oggetto classe che si definisce come solo aggregabile.

Osservazioni:

DECLARE_ONLY_AGGREGATABLE genera un errore (E_FAIL) se viene effettuato un tentativo all'oggetto CoCreate come oggetto nonaggregato.

Per impostazione predefinita, CComCoClass contiene la macro DECLARE_AGGREGATABLE , che specifica che l'oggetto può essere aggregato. Per eseguire l'override di questo comportamento predefinito, includere DECLARE_ONLY_AGGREGATABLE nella definizione della classe.

Esempio

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

   DECLARE_ONLY_AGGREGATABLE(COnlyAggClass)
};

DECLARE_POLY_AGGREGATABLE

Specifica che viene creata un'istanza di CComPolyObject < x > al momento della creazione dell'oggetto.

DECLARE_POLY_AGGREGATABLE( x )

Parametri

x
[in] Nome dell'oggetto classe che si definisce come aggregabile o non aggregabile.

Osservazioni:

Durante la creazione, viene controllato il valore dell'elemento sconosciuto esterno. Se è NULL, IUnknown viene implementato per un oggetto nonaggregato. Se l'elemento sconosciuto esterno non è NULL, IUnknown viene implementato per un oggetto aggregato.

Il vantaggio dell'uso di DECLARE_POLY_AGGREGATABLE consiste nell'evitare di avere sia CComAggObject che CComObject nel modulo per gestire i casi aggregati e non aggregati. Un singolo CComPolyObject oggetto gestisce entrambi i casi. Ciò significa che nel modulo è presente una sola copia della tabella virtuale e una copia delle funzioni. Se la tabella virtuale è grande, questa operazione può ridurre notevolmente le dimensioni del modulo. Tuttavia, se la tabella virtuale è piccola, l'uso CComPolyObject di può comportare dimensioni del modulo leggermente maggiori perché non è ottimizzato per un oggetto aggregato o nonaggregato, come sono CComAggObject e CComObject.

La macro DECLARE_POLY_AGGREGATABLE viene dichiarata automaticamente nell'oggetto se si utilizza la Creazione guidata controllo ATL per creare un controllo completo.

DECLARE_PROTECT_FINAL_CONSTRUCT

Protegge l'oggetto dall'eliminazione se (durante FinalConstruct) l'oggetto aggregato interno incrementa il conteggio dei riferimenti e quindi decrementa il conteggio su 0.

DECLARE_PROTECT_FINAL_CONSTRUCT()

DECLARE_VIEW_STATUS

Posizionare questa macro nella classe di controllo di un controllo ActiveX ATL per specificare i flag VIEWSTATUS nel contenitore.

DECLARE_VIEW_STATUS( statusFlags )

Parametri

statusFlags
[in] Flag VIEWSTATUS. Per un elenco di flag, vedere VIEWSTATUS .

Esempio

DECLARE_VIEW_STATUS(VIEWSTATUS_SOLIDBKGND | VIEWSTATUS_OPAQUE)

Vedi anche

Macro