IClassFactory::CreateInstance-Methode (unknwn.h)
Erstellt ein nicht initialisiertes Objekt.
Syntax
HRESULT CreateInstance(
[in] IUnknown *pUnkOuter,
[in] REFIID riid,
[out] void **ppvObject
);
Parameter
[in] pUnkOuter
Wenn das Objekt als Teil eines Aggregats erstellt wird, geben Sie einen Zeiger auf die steuernde IUnknown-Schnittstelle des Aggregats an. Andernfalls muss dieser Parameter NULL sein.
[in] riid
Ein Verweis auf den Bezeichner der Schnittstelle, die für die Kommunikation mit dem neu erstellten Objekt verwendet werden soll. Wenn pUnkOuterNULL ist, ist dieser Parameter im Allgemeinen die IID der Initialisierungsschnittstelle. wenn pUnkOuter nicht NULL ist, muss riid IID_IUnknown sein.
[out] ppvObject
Die Adresse der Zeigervariable, die den in riid angeforderten Schnittstellenzeiger empfängt. Nach erfolgreicher Rückgabe enthält *ppvObject den angeforderten Schnittstellenzeiger. Wenn das Objekt die in riid angegebene Schnittstelle nicht unterstützt, muss die Implementierung *ppvObject auf NULL festlegen.
Rückgabewert
Diese Methode kann die Standardrückgabewerte E_INVALIDARG, E_OUTOFMEMORY und E_UNEXPECTED sowie die folgenden Werte zurückgeben.
| Rückgabecode | BESCHREIBUNG |
|---|---|
|
Das angegebene Objekt wurde erstellt. |
|
Der pUnkOuter-Parameter war nicht NULL , und das Objekt unterstützt keine Aggregation. |
|
Das Objekt, auf das ppvObject verweist, unterstützt die durch riid identifizierte Schnittstelle nicht. |
Hinweise
Die Implementierung von CreateInstance eines COM-Servers muss einen Verweis auf ein Objekt zurückgeben, das in einem Apartment enthalten ist, das zum DCOM-Resolver des Servers gehört. Es darf keinen Verweis auf ein Objekt zurückgeben, das in einem Remoteapartment enthalten ist.
Die IClassFactory-Schnittstelle befindet sich immer in einem Klassenobjekt. Die CreateInstance-Methode erstellt ein nicht initialisiertes Objekt der Klasse, die mit der angegebenen CLSID identifiziert wurde. Wenn ein Objekt auf diese Weise erstellt wird, muss die CLSID in der Systemregistrierung mit der CoRegisterClassObject-Funktion registriert werden.
Der pUnkOuter-Parameter gibt an, ob das Objekt als Teil eines Aggregats erstellt wird. Objektdefinitionen sind nicht erforderlich, um die Aggregation zu unterstützen. Sie müssen speziell entworfen und implementiert werden, um sie zu unterstützen.
Der riid-Parameter gibt den IID (Schnittstellenbezeichner) der Schnittstelle an, über die Sie mit dem neuen Objekt kommunizieren. Wenn pUnkOuter nicht NULL ist (die Aggregation angibt), muss der Wert des riid-Parameters IID_IUnknown sein. Wenn das Objekt nicht Teil eines Aggregats ist, gibt riid häufig die Schnittstelle an, über die das Objekt initialisiert wird.
Für OLE-Einbettungen ist die Initialisierungsschnittstelle IPersistStorage, in anderen Situationen werden jedoch andere Schnittstellen verwendet. Um das Objekt zu initialisieren, muss in der Initialisierungsschnittstelle ein nachfolgender Aufruf einer entsprechenden Methode vorhanden sein. Zu den gängigen Initialisierungsfunktionen gehören IPersistStorage::InitNew (für neue, leere einbettbare Komponenten), IPersistStorage::Load (für neu geladene einbettbare Komponenten), IPersistStream::Load, (für Objekte, die in einem Streamobjekt gespeichert sind) oder IPersistFile::Load (für in einer Datei gespeicherte Objekte).
Wenn eine Anwendung nur eine Klasse von Objekten unterstützt und das Klassenobjekt zur einmaligen Verwendung registriert ist, kann im Allgemeinen nur ein Objekt erstellt werden. Die Anwendung darf keine anderen Objekte erstellen, und eine Anforderung dazu sollte einen Fehler von IClassFactory::CreateInstance zurückgeben. Gleiches gilt für Anwendungen, die mehrere Klassen unterstützen, jeweils mit einem Klassenobjekt, das für die einmalige Verwendung registriert ist. Ein Aufruf von CreateInstance für eine Klasse gefolgt von einem Aufruf von CreateInstance für eine der Klassen, die einen Fehler zurückgeben soll.
Um das Zurückgeben eines Fehlers zu vermeiden, können Anwendungen, die mehrere Klassen mit Einzelverwendungsklassenobjekten unterstützen, das registrierte Klassenobjekt der ersten Klasse widerrufen, indem Sie CoRevokeClassObject aufrufen, wenn eine Anforderung zum Instanziieren einer Zweiten empfangen wird. Angenommen, es gibt zwei Klassen, A und B. Wenn CreateInstance für Klasse A aufgerufen wird, widerrufen Sie das Klassenobjekt für B. Wenn B erstellt wird, widerrufen Sie das Klassenobjekt für A. Diese Lösung erschwert das Herunterfahren, da eines der Klassenobjekte möglicherweise bereits widerrufen wurde (und nicht zweimal widerrufen werden kann).
Anforderungen
| Unterstützte Mindestversion (Client) | Windows 2000 Professional [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | unknwn.h |