Agrégation et macros de fabrique de classe

Ces macros permettent de contrôler l’agrégation et de déclarer des fabriques de classes.

Spécifications

En-tête : atlcom.h

DECLARE_AGGREGATABLE

Spécifie que votre objet peut être agrégé.

DECLARE_AGGREGATABLE( x )

Paramètres

x
[in] Nom de la classe que vous définissez comme aggregatable.

Notes

CComCoClass contient cette macro pour spécifier le modèle d’agrégation par défaut. Pour remplacer cette valeur par défaut, spécifiez la macro DECLARE_NOT_AGGREGATABLE ou DECLARE_ONLY_AGGREGATABLE dans votre définition de classe.

Exemple

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

   DECLARE_NOT_AGGREGATABLE(CNoAggClass)
};

DECLARE_CLASSFACTORY

Déclare CComClassFactory comme fabrique de classe.

DECLARE_CLASSFACTORY()

Notes

CComCoClass utilise cette macro pour déclarer la fabrique de classes par défaut pour votre objet.

Exemple

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, classe

Cette classe implémente l’interface IClassFactory .

class CComClassFactory : public IClassFactory,
public CComObjectRootEx<CComGlobalsThreadModel>

Notes

CComClassFactoryimplémente l’interface IClassFactory, qui contient des méthodes de création d’un objet d’un CLSID particulier, ainsi que le verrouillage de la fabrique de classes en mémoire pour permettre la création plus rapidement de nouveaux objets. IClassFactory doit être implémenté pour chaque classe que vous inscrivez dans le registre système et à laquelle vous attribuez un CLSID.

Les objets ATL acquièrent normalement une fabrique de classes en dérivant de CComCoClass. Cette classe inclut la macro DECLARE_CLASSFACTORY, qui déclare CComClassFactory comme fabrique de classes par défaut. Pour remplacer cette valeur par défaut, spécifiez l’une des macros DECLARE_CLASSFACTORYXXX dans votre définition de classe. Par exemple, la macro DECLARE_CLASSFACTORY_EX utilise la classe spécifiée pour la fabrique 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.

La définition de classe ci-dessus spécifie qu’elle CMyClassFactory sera utilisée comme fabrique de classe par défaut de l’objet. CMyClassFactory doit dériver et CComClassFactory remplacer CreateInstance.

ATL fournit trois autres macros qui déclarent une fabrique de classes :

• DECLARE_CLASSFACTORY2 utilise CComClassFactory2, qui contrôle la création via une licence.

• DECLARE_CLASSFACTORY_AUTO_THREAD Utilise CComClassFactoryAutoThread, qui crée des objets dans plusieurs appartements.

• DECLARE_CLASSFACTORY_SINGLETON Utilise CComClassFactorySingleton, qui construit un seul objet CComObjectGlobal.

DECLARE_CLASSFACTORY_EX

cf Déclare être la fabrique de classes.

DECLARE_CLASSFACTORY_EX( cf )

Paramètres

cf
[in] Nom de la classe qui implémente votre objet fabrique de classe.

Notes

Le paramètre cf doit dériver de CComClassFactory et remplacer la CreateInstance méthode.

CComCoClass inclut la macro DECLARE_CLASSFACTORY , qui spécifie CComClassFactory comme fabrique de classes par défaut. Toutefois, en incluant la macro DECLARE_CLASSFACTORY_EX dans la définition de classe de votre objet, vous remplacez cette valeur par défaut.

Exemple

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

Déclare CComClassFactory2 comme fabrique de classe.

DECLARE_CLASSFACTORY2( lic )

Paramètres

lic
[in] Classe qui implémente VerifyLicenseKey, GetLicenseKeyet IsLicenseValid.

Notes

CComCoClass inclut la macro DECLARE_CLASSFACTORY , qui spécifie CComClassFactory comme fabrique de classe par défaut. Toutefois, en incluant la macro DECLARE_CLASSFACTORY2 dans la définition de classe de votre objet, vous remplacez cette valeur par défaut.

Exemple

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

CComClassFactory2, classe

Cette classe implémente l’interface IClassFactory2 .

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

Paramètres

licence
Classe qui implémente les fonctions statiques suivantes :

• static BOOL VerifyLicenseKey( BSTR bstr );

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

• static BOOL IsLicenseValid( );

Notes

CComClassFactory2 implémente l’interface IClassFactory2 , qui est une extension de IClassFactory. IClassFactory2 contrôle la création d’objets via une licence. Une fabrique de classes s’exécutant sur une machine sous licence peut fournir une clé de licence au moment de l’exécution. Cette clé de licence permet à une application d’instancier des objets lorsqu’une licence d’ordinateur complète n’existe pas.

Les objets ATL acquièrent normalement une fabrique de classes en dérivant de CComCoClass. Cette classe inclut la macro DECLARE_CLASSFACTORY, qui déclare CComClassFactory comme fabrique de classe par défaut. Pour utiliser CComClassFactory2, spécifiez la macro DECLARE_CLASSFACTORY2 dans la définition de classe de votre objet. Par exemple :

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, le paramètre de modèle sur CComClassFactory2, doit implémenter les fonctions statiques VerifyLicenseKey, GetLicenseKeyet IsLicenseValid. Voici un exemple de classe de licence 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 dérive à la fois CComClassFactory2Base de la licence et de la licence. CComClassFactory2Base, à son tour, dérive de IClassFactory2 et CComObjectRootEx< CComGlobalsThreadModel >.

DECLARE_CLASSFACTORY_AUTO_THREAD

Déclare CComClassFactoryAutoThread comme fabrique de classe.

DECLARE_CLASSFACTORY_AUTO_THREAD()

Notes

CComCoClass inclut la macro DECLARE_CLASSFACTORY , qui spécifie CComClassFactory comme fabrique de classe par défaut. Toutefois, en incluant la macro DECLARE_CLASSFACTORY_AUTO_THREAD dans la définition de classe de votre objet, vous remplacez cette valeur par défaut.

Lorsque vous créez des objets dans plusieurs appartements (dans un serveur hors processus), ajoutez DECLARE_CLASSFACTORY_AUTO_THREAD à votre classe.

Exemple

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, classe

Cette classe implémente l’interface IClassFactory et permet de créer des objets dans plusieurs appartements.

class CComClassFactoryAutoThread : public IClassFactory,
public CComObjectRootEx<CComGlobalsThreadModel>

Notes

CComClassFactoryAutoThread est similaire à CComClassFactory, mais permet de créer des objets dans plusieurs appartements. Pour tirer parti de cette prise en charge, dérivez votre module EXE de CComAutoThreadModule.

Les objets ATL acquièrent normalement une fabrique de classes en dérivant de CComCoClass. Cette classe inclut la macro DECLARE_CLASSFACTORY, qui déclare CComClassFactory comme fabrique de classe par défaut. Pour utiliser CComClassFactoryAutoThread, spécifiez la macro DECLARE_CLASSFACTORY_AUTO_THREAD dans la définition de classe de votre objet. Par exemple :

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

Déclare CComClassFactorySingleton comme fabrique de classe.

DECLARE_CLASSFACTORY_SINGLETON( obj )

Paramètres

obj
[in] Nom de votre objet de classe.

Notes

CComCoClass inclut la macro DECLARE_CLASSFACTORY , qui spécifie CComClassFactory comme fabrique de classe par défaut. Toutefois, en incluant la macro DECLARE_CLASSFACTORY_SINGLETON dans la définition de classe de votre objet, vous remplacez cette valeur par défaut.

Exemple

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, classe

Cette classe dérive de CComClassFactory et utilise CComObjectGlobal pour construire un seul objet.

template<class T>
class CComClassFactorySingleton : public CComClassFactory

Paramètres

T
Votre classe.

CComClassFactorySingleton dérive de CComClassFactory et utilise CComObjectGlobal pour construire un seul objet. Chaque appel à la CreateInstance méthode interroge simplement cet objet pour un pointeur d’interface.

Notes

Les objets ATL acquièrent normalement une fabrique de classes en dérivant de CComCoClass. Cette classe inclut la macro DECLARE_CLASSFACTORY, qui déclare CComClassFactory comme fabrique de classes par défaut. Pour utiliser CComClassFactorySingleton, spécifiez la macro DECLARE_CLASSFACTORY_SINGLETON dans la définition de classe de votre objet. Par exemple :

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

Déclare une fonction GetControllingUnknownvirtuelle .

DECLARE_GET_CONTROLLING_UNKNOWN()

Notes

Ajoutez cette macro à votre objet si vous obtenez le message d’erreur du compilateur qui GetControllingUnknown n’est pas défini (par exemple, dans CComAggregateCreator).

DECLARE_NOT_AGGREGATABLE

Spécifie que votre objet ne peut pas être agrégé.

DECLARE_NOT_AGGREGATABLE( x )

Paramètres

x
[in] Nom de l’objet de classe que vous définissez comme non aggregatable.

Notes

DECLARE_NOT_AGGREGATABLE provoque CreateInstance un retour d’erreur (CLASS_E_NOAGGREGATION) si une tentative d’agrégation sur votre objet est effectuée.

Par défaut, CComCoClass contient la macro DECLARE_AGGREGATABLE , qui spécifie que votre objet peut être agrégé. Pour remplacer ce comportement par défaut, incluez DECLARE_NOT_AGGREGATABLE dans votre définition de classe.

Exemple

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

   DECLARE_NOT_AGGREGATABLE(CNoAggClass)
};

DECLARE_ONLY_AGGREGATABLE

Spécifie que votre objet doit être agrégé.

DECLARE_ONLY_AGGREGATABLE( x )

Paramètres

x
[in] Nom de l’objet de classe que vous définissez comme étant uniquement aggregatable.

Notes

DECLARE_ONLY_AGGREGATABLE provoque une erreur (E_FAIL) si une tentative est effectuée sur CoCreate votre objet comme objet non agrégé.

Par défaut, CComCoClass contient la macro DECLARE_AGGREGATABLE , qui spécifie que votre objet peut être agrégé. Pour remplacer ce comportement par défaut, incluez DECLARE_ONLY_AGGREGATABLE dans votre définition de classe.

Exemple

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

   DECLARE_ONLY_AGGREGATABLE(COnlyAggClass)
};

DECLARE_POLY_AGGREGATABLE

Spécifie qu’une instance de CComPolyObject < x > est créée lors de la création de votre objet.

DECLARE_POLY_AGGREGATABLE( x )

Paramètres

x
[in] Nom de l’objet de classe que vous définissez comme aggregatable ou non aggregatable.

Notes

Lors de la création, la valeur de l’inconnu externe est vérifiée. S’il s’agit de NULL, IUnknown est implémenté pour un objet non agrégé. Si l’inconnu externe n’est pas NULL, IUnknown est implémenté pour un objet agrégé.

L’avantage d’utiliser DECLARE_POLY_AGGREGATABLE est que vous évitez d’avoir à la fois CComAggObject et CComObject dans votre module pour gérer les cas agrégés et non agrégés. Un objet unique CComPolyObject gère les deux cas. Cela signifie qu’une seule copie de la table virtuelle et une copie des fonctions existent dans votre module. Si votre vtable est volumineux, cela peut réduire considérablement la taille de votre module. Toutefois, si votre vtable est petit, l’utilisation CComPolyObject peut entraîner une taille de module légèrement plus grande, car elle n’est pas optimisée pour un objet agrégé ou non agrégé, comme c’est le cas CComAggObject et CComObject.

La macro DECLARE_POLY_AGGREGATABLE est automatiquement déclarée dans votre objet si vous utilisez l’Assistant Contrôle ATL pour créer un contrôle total.

DECLARE_PROTECT_FINAL_CONSTRUCT

Protège votre objet contre la suppression si (pendant FinalConstruct) l’objet agrégé interne incrémente le nombre de références, décrémente le nombre de références à 0.

DECLARE_PROTECT_FINAL_CONSTRUCT()

DECLARE_VIEW_STATUS

Placez cette macro dans la classe de contrôle d’un contrôle ATL ActiveX pour spécifier les indicateurs VIEWSTATUS dans le conteneur.

DECLARE_VIEW_STATUS( statusFlags )

Paramètres

statusFlags
[in] Indicateurs VIEWSTATUS. Consultez VIEWSTATUS pour obtenir la liste des indicateurs.

Exemple

DECLARE_VIEW_STATUS(VIEWSTATUS_SOLIDBKGND | VIEWSTATUS_OPAQUE)

Voir aussi

Macros