Makra agregacji i fabryki klas
Te makra zapewniają sposoby kontrolowania agregacji i deklarowania fabryk klas.
| Makro | opis |
|---|---|
| DECLARE_AGGREGATABLE | Deklaruje, że obiekt można agregować (wartość domyślna). |
| DECLARE_CLASSFACTORY | Deklaruje fabrykę klas jako CComClassFactory, domyślną fabrykę klas ATL. |
| DECLARE_CLASSFACTORY_EX | Deklaruje obiekt fabryki klas jako fabrykę klas. |
| DECLARE_CLASSFACTORY2 | Deklaruje klasę CComClassFactory2 jako fabrykę klas. |
| DECLARE_CLASSFACTORY_AUTO_THREAD | Deklaruje klasę CComClassFactoryAutoThread jako fabrykę klas. |
| DECLARE_CLASSFACTORY_SINGLETON | Deklaruje klasę CComClassFactorySingleton jako fabrykę klas. |
| DECLARE_GET_CONTROLLING_UNKNOWN | Deklaruje funkcję wirtualną GetControllingUnknown . |
| DECLARE_NOT_AGGREGATABLE | Deklaruje, że nie można agregować obiektu. |
| DECLARE_ONLY_AGGREGATABLE | Deklaruje, że obiekt musi być zagregowany. |
| DECLARE_POLY_AGGREGATABLE | Sprawdza wartość zewnętrznej nieznanej i deklaruje, że obiekt jest aggregatable lub nie jest aggregatable, zgodnie z potrzebami. |
| DECLARE_PROTECT_FINAL_CONSTRUCT | Chroni obiekt zewnętrzny przed usunięciem podczas budowy obiektu wewnętrznego. |
| DECLARE_VIEW_STATUS | Określa flagi VIEWSTATUS kontenera. |
Wymagania
Nagłówek: atlcom.h
DECLARE_AGGREGATABLE
Określa, że obiekt można agregować.
DECLARE_AGGREGATABLE( x )
Parametry
x
[in] Nazwa klasy definiowanej jako aggregatable.
Uwagi
Klasa CComCoClass zawiera to makro, aby określić domyślny model agregacji. Aby zastąpić tę wartość domyślną, określ makro DECLARE_NOT_AGGREGATABLE lub DECLARE_ONLY_AGGREGATABLE w definicji klasy.
Przykład
class ATL_NO_VTABLE CNoAggClass :
public CComObjectRoot,
public CComCoClass<CNoAggClass, &CLSID_NoAggClass>
{
public:
CNoAggClass()
{
}
DECLARE_NOT_AGGREGATABLE(CNoAggClass)
};
DECLARE_CLASSFACTORY
Deklaruje CComClassFactory jako fabrykę klas.
DECLARE_CLASSFACTORY()
Uwagi
Klasa CComCoClass używa tego makra do deklarowania domyślnej fabryki klas dla obiektu.
Przykład
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
Klasa CComClassFactory
Ta klasa implementuje interfejs IClassFactory .
class CComClassFactory : public IClassFactory,
public CComObjectRootEx<CComGlobalsThreadModel>
Uwagi
CComClassFactory implementuje interfejs IClassFactory , który zawiera metody tworzenia obiektu określonego identyfikatora CLSID, a także blokowanie fabryki klas w pamięci w celu umożliwienia szybszego tworzenia nowych obiektów. IClassFactory Należy zaimplementować dla każdej klasy, która jest rejestrowana w rejestrze systemowym i do której przypisujesz identyfikator CLSID.
Obiekty ATL zwykle uzyskują fabrykę klas, wyprowadzając je z klasy CComCoClass. Ta klasa zawiera DECLARE_CLASSFACTORY makra, które deklaruje CComClassFactory jako domyślną fabrykę klas. Aby zastąpić tę wartość domyślną, określ jedno z makr DECLARE_CLASSFACTORYXXX w definicji klasy. Na przykład makro DECLARE_CLASSFACTORY_EX używa określonej klasy dla fabryki klas:
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.
Powyższa definicja klasy określa, że CMyClassFactory będzie używany jako domyślna fabryka klas obiektu. CMyClassFactory musi pochodzić z i CComClassFactory zastąpić CreateInstance.
ATL udostępnia trzy inne makra, które deklarują fabrykę klas:
DECLARE_CLASSFACTORY2 używa klasy CComClassFactory2, która kontroluje tworzenie za pośrednictwem licencji.
DECLARE_CLASSFACTORY_AUTO_THREAD używa klasy CComClassFactoryAutoThread, która tworzy obiekty w wielu mieszkaniach.
DECLARE_CLASSFACTORY_SINGLETON używa klasy CComClassFactorySingleton, która tworzy pojedynczy obiekt CComObjectGlobal.
DECLARE_CLASSFACTORY_EX
cf Deklaruje, że jest fabryką klas.
DECLARE_CLASSFACTORY_EX( cf )
Parametry
por
[in] Nazwa klasy, która implementuje obiekt fabryki klas.
Uwagi
Parametr cf musi pochodzić z CComClassFactory i zastąpić metodę CreateInstance .
Klasa CComCoClass zawiera makro DECLARE_CLASSFACTORY , które określa CComClassFactory jako domyślną fabrykę klas. Jednak przez uwzględnienie makra DECLARE_CLASSFACTORY_EX w definicji klasy obiektu zastąpisz tę wartość domyślną.
Przykład
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
Deklaruje klasę CComClassFactory2 jako fabrykę klas.
DECLARE_CLASSFACTORY2( lic )
Parametry
lic
[in] Klasa, która implementuje VerifyLicenseKey, GetLicenseKeyi IsLicenseValid.
Uwagi
Klasa CComCoClass zawiera makro DECLARE_CLASSFACTORY, które określa CComClassFactory jako domyślną fabrykę klas. Jednak przez uwzględnienie makra DECLARE_CLASSFACTORY2 w definicji klasy obiektu należy zastąpić tę wartość domyślną.
Przykład
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
Klasa CComClassFactory2
Ta klasa implementuje interfejs IClassFactory2 .
template <class license>
class CComClassFactory2 : public IClassFactory2,
public CComObjectRootEx<CComGlobalsThreadModel>,
public license
Parametry
licencja
Klasa, która implementuje następujące funkcje statyczne:
static BOOL VerifyLicenseKey( BSTR bstr );static BOOL GetLicenseKey( DWORD dwReserved, BSTR * pBstr );static BOOL IsLicenseValid( );
Uwagi
CComClassFactory2 implementuje interfejs IClassFactory2 , który jest rozszerzeniem IClassFactory. IClassFactory2 steruje tworzeniem obiektów za pośrednictwem licencji. Fabryka klas wykonująca na licencjonowanej maszynie może zapewnić klucz licencji w czasie wykonywania. Ten klucz licencji umożliwia aplikacji utworzenie wystąpienia obiektów, gdy pełna licencja maszyny nie istnieje.
Obiekty ATL zwykle uzyskują fabrykę klas, wyprowadzając je z klasy CComCoClass. Ta klasa zawiera DECLARE_CLASSFACTORY makra, które deklaruje CComClassFactory jako domyślną fabrykę klas. Aby użyć CComClassFactory2metody , określ makro DECLARE_CLASSFACTORY2 w definicji klasy obiektu. Na przykład:
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, parametr szablonu do CComClassFactory2, musi implementować funkcje VerifyLicenseKeystatyczne , GetLicenseKeyi IsLicenseValid. Poniżej przedstawiono przykład prostej klasy licencji:
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; }
};
CComClassFactory2pochodzi zarówno z licencji, jak CComClassFactory2Base i . CComClassFactory2Base, z kolei pochodzi z IClassFactory2 i CComObjectRootEx< CComGlobalsThreadModel >.
DECLARE_CLASSFACTORY_AUTO_THREAD
Deklaruje klasę CComClassFactoryAutoThread jako fabrykę klas.
DECLARE_CLASSFACTORY_AUTO_THREAD()
Uwagi
Klasa CComCoClass zawiera makro DECLARE_CLASSFACTORY, które określa CComClassFactory jako domyślną fabrykę klas. Jednak przez uwzględnienie makra DECLARE_CLASSFACTORY_AUTO_THREAD w definicji klasy obiektu należy zastąpić tę wartość domyślną.
Podczas tworzenia obiektów w wielu mieszkaniach (na serwerze out-of-proc) dodaj DECLARE_CLASSFACTORY_AUTO_THREAD do klasy.
Przykład
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.
Klasa CComClassFactoryAutoThread
Ta klasa implementuje interfejs IClassFactory i umożliwia tworzenie obiektów w wielu mieszkaniach.
Ważne
Tej klasy i jej składowych nie można używać w aplikacjach wykonywanych w środowisko wykonawcze systemu Windows.
class CComClassFactoryAutoThread : public IClassFactory,
public CComObjectRootEx<CComGlobalsThreadModel>
Uwagi
CComClassFactoryAutoThread jest podobny do CComClassFactory, ale umożliwia tworzenie obiektów w wielu mieszkaniach. Aby skorzystać z tej obsługi, utwórz moduł EXE z modułu CComAutoThreadModule.
Obiekty ATL zwykle uzyskują fabrykę klas, wyprowadzając je z klasy CComCoClass. Ta klasa zawiera DECLARE_CLASSFACTORY makra, które deklaruje CComClassFactory jako domyślną fabrykę klas. Aby użyć CComClassFactoryAutoThreadmetody , określ makro DECLARE_CLASSFACTORY_AUTO_THREAD w definicji klasy obiektu. Na przykład:
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
Deklaruje klasę CComClassFactorySingleton jako fabrykę klas.
DECLARE_CLASSFACTORY_SINGLETON( obj )
Parametry
Obj
[in] Nazwa obiektu klasy.
Uwagi
Klasa CComCoClass zawiera makro DECLARE_CLASSFACTORY, które określa CComClassFactory jako domyślną fabrykę klas. Jednak po uwzględnieniu makra DECLARE_CLASSFACTORY_SINGLETON w definicji klasy obiektu zastąpisz tę wartość domyślną.
Przykład
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.
Klasa CComClassFactorySingleton
Ta klasa pochodzi z klasy CComClassFactory i używa obiektu CComObjectGlobal do konstruowania pojedynczego obiektu.
Ważne
Tej klasy i jej składowych nie można używać w aplikacjach wykonywanych w środowisko wykonawcze systemu Windows.
template<class T>
class CComClassFactorySingleton : public CComClassFactory
Parametry
T
Klasa.
CComClassFactorySingleton element pochodzi z klasy CComClassFactory i używa obiektu CComObjectGlobal do konstruowania pojedynczego obiektu. Każde wywołanie CreateInstance metody po prostu odpytuje ten obiekt dla wskaźnika interfejsu.
Uwagi
Obiekty ATL zwykle uzyskują fabrykę klas, wyprowadzając je z klasy CComCoClass. Ta klasa zawiera DECLARE_CLASSFACTORY makra, które deklaruje CComClassFactory jako domyślną fabrykę klas. Aby użyć CComClassFactorySingletonmetody , określ makro DECLARE_CLASSFACTORY_SINGLETON w definicji klasy obiektu. Na przykład:
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
Deklaruje funkcję GetControllingUnknownwirtualną .
DECLARE_GET_CONTROLLING_UNKNOWN()
Uwagi
Dodaj to makro do obiektu, jeśli zostanie wyświetlony komunikat o błędzie kompilatora, który GetControllingUnknown jest niezdefiniowany (na przykład w pliku CComAggregateCreator).
DECLARE_NOT_AGGREGATABLE
Określa, że nie można agregować obiektu.
DECLARE_NOT_AGGREGATABLE( x )
Parametry
x
[in] Nazwa obiektu klasy, który definiujesz jako nie aggregatable.
Uwagi
DECLARE_NOT_AGGREGATABLE powoduje CreateInstance zwrócenie błędu (CLASS_E_NOAGGREGATION), jeśli zostanie podjęta próba zagregowania na obiekcie.
Domyślnie klasa CComCoClass zawiera makro DECLARE_AGGREGATABLE , które określa, że obiekt można agregować. Aby zastąpić to zachowanie domyślne, uwzględnij DECLARE_NOT_AGGREGATABLE w definicji klasy.
Przykład
class ATL_NO_VTABLE CNoAggClass :
public CComObjectRoot,
public CComCoClass<CNoAggClass, &CLSID_NoAggClass>
{
public:
CNoAggClass()
{
}
DECLARE_NOT_AGGREGATABLE(CNoAggClass)
};
DECLARE_ONLY_AGGREGATABLE
Określa, że obiekt musi być agregowany.
DECLARE_ONLY_AGGREGATABLE( x )
Parametry
x
[in] Nazwa obiektu klasy, który definiujesz jako tylko aggregatable.
Uwagi
DECLARE_ONLY_AGGREGATABLE powoduje błąd (E_FAIL), jeśli próba zostanie podjęta w CoCreate obiekcie jako obiekt nieagregowany.
Domyślnie klasa CComCoClass zawiera makro DECLARE_AGGREGATABLE , które określa, że obiekt można agregować. Aby zastąpić to zachowanie domyślne, uwzględnij DECLARE_ONLY_AGGREGATABLE w definicji klasy.
Przykład
class ATL_NO_VTABLE COnlyAggClass :
public CComObjectRoot,
public CComCoClass<COnlyAggClass, &CLSID_OnlyAggClass>
{
public:
COnlyAggClass()
{
}
DECLARE_ONLY_AGGREGATABLE(COnlyAggClass)
};
DECLARE_POLY_AGGREGATABLE
Określa, że wystąpienie obiektu CComPolyObject < x > jest tworzone podczas tworzenia obiektu.
DECLARE_POLY_AGGREGATABLE( x )
Parametry
x
[in] Nazwa obiektu klasy definiowanego jako aggregatable lub nie aggregatable.
Uwagi
Podczas tworzenia sprawdzana jest wartość zewnętrznej nieznanej. Jeśli ma wartość NULL, IUnknown jest implementowany dla obiektu nieagregowanego. Jeśli zewnętrzna nieznana wartość nie ma wartości NULL, IUnknown jest implementowana dla zagregowanego obiektu.
Zaletą korzystania z DECLARE_POLY_AGGREGATABLE jest unikanie CComAggObject obsługi zagregowanych i nieagregowanych przypadków zarówno w module, jak i CComObject w module. Pojedynczy CComPolyObject obiekt obsługuje oba przypadki. Oznacza to, że w module istnieje tylko jedna kopia tabeli wirtualnej i jedna kopia funkcji. Jeśli twoja tabela wirtualna jest duża, może to znacznie zmniejszyć rozmiar modułu. Jeśli jednak tabela wirtualna jest mała, użycie CComPolyObject metody może spowodować nieco większy rozmiar modułu, ponieważ nie jest zoptymalizowany pod kątem zagregowanego lub nieagregowanego obiektu, podobnie jak i CComAggObject CComObject.
Makro DECLARE_POLY_AGGREGATABLE jest automatycznie deklarowane w obiekcie, jeśli używasz Kreatora kontrolek ATL do utworzenia pełnej kontroli.
DECLARE_PROTECT_FINAL_CONSTRUCT
Chroni obiekt przed usunięciem, jeśli (podczas finalConstruct) wewnętrzny zagregowany obiekt zwiększa liczbę odwołań, a następnie dekrementuje liczbę do 0.
DECLARE_PROTECT_FINAL_CONSTRUCT()
DECLARE_VIEW_STATUS
Umieść to makro w klasie kontrolki ACTIVEX ATL, aby określić flagi VIEWSTATUS do kontenera.
DECLARE_VIEW_STATUS( statusFlags )
Parametry
statusFlags
[in] Flagi VIEWSTATUS. Zobacz VIEWSTATUS , aby uzyskać listę flag.
Przykład
DECLARE_VIEW_STATUS(VIEWSTATUS_SOLIDBKGND | VIEWSTATUS_OPAQUE)