CoCreateInstanceEx-Funktion (combaseapi.h)

Artikel
02/28/2024

Erstellt eine instance einer bestimmten Klasse auf einem bestimmten Computer.

Syntax

HRESULT CoCreateInstanceEx(
  [in]      REFCLSID     Clsid,
  [in]      IUnknown     *punkOuter,
  [in]      DWORD        dwClsCtx,
  [in]      COSERVERINFO *pServerInfo,
  [in]      DWORD        dwCount,
  [in, out] MULTI_QI     *pResults
);

Parameter

[in] Clsid

Die CLSID des zu erstellenden Objekts.

[in] punkOuter

Wenn dieser Parameter nicht NULL ist, gibt an, dass die instance als Teil eines Aggregats erstellt wird, und PunkOuter als die neue instance verwendet werden soll, die IUnknown steuert. Die Aggregation wird derzeit nicht prozess- oder computerübergreifend unterstützt. Beim Instanziieren eines Objekts aus dem Prozess wird CLASS_E_NOAGGREGATION zurückgegeben, wenn punkOuter nicht NULL ist.

[in] dwClsCtx

Ein Wert aus der CLSCTX-Enumeration .

[in] pServerInfo

Informationen zum Computer, auf dem das Objekt instanziieren soll. Weitere Informationen finden Sie unter COSERVERINFO. Dieser Parameter kann NULL sein. In diesem Fall wird das Objekt auf dem lokalen Computer oder auf dem computer instanziiert, der in der Registrierung unter dem RemoteServerName-Wert der Klasse angegeben ist, entsprechend der Interpretation des dwClsCtx-Parameters .

[in] dwCount

Die Anzahl der Strukturen in pResults. Dieser Wert muss größer als 0 sein.

[in, out] pResults

Ein Array von MULTI_QI Strukturen. Jede Struktur verfügt über drei Member: den Bezeichner für eine angeforderte Schnittstelle (pIID), den Speicherort zum Zurückgeben des Schnittstellenzeigers (pItf) und den Rückgabewert des Aufrufs von QueryInterface (hr).

Rückgabewert

Diese Funktion kann den Standardrückgabewert E_INVALIDARG sowie die folgenden Werte zurückgeben.

Rückgabecode	BESCHREIBUNG
S_OK	Gibt die erfolgreiche Ausführung an.
REGDB_E_CLASSNOTREG	Eine angegebene Klasse ist nicht in der Registrierungsdatenbank registriert. Kann auch angeben, dass der Servertyp, den Sie in der CLSCTX-Enumeration angefordert haben, nicht registriert ist oder dass die Werte für die Servertypen in der Registrierung beschädigt sind.
CLASS_E_NOAGGREGATION	Diese Klasse kann nicht als Teil eines Aggregats erstellt werden.
CO_S_NOTALLINTERFACES	Mindestens eine, aber nicht alle im pResults-Array angeforderten Schnittstellen wurden erfolgreich abgerufen. Der hr-Member jeder MULTI_QI-Struktur in pResults gibt mit S_OK oder E_NOINTERFACE an, ob die spezifische Schnittstelle zurückgegeben wurde.
E_NOINTERFACE	Keine der im pResults-Array angeforderten Schnittstellen wurde erfolgreich abgerufen.

Hinweise

CoCreateInstanceEx erstellt ein einzelnes nicht initialisiertes Objekt, das der angegebenen CLSID auf einem angegebenen Remotecomputer zugeordnet ist. Dies ist eine Erweiterung der Funktion CoCreateInstance, die nur auf dem lokalen Computer ein Objekt erstellt. Darüber hinaus ermöglicht CoCreateInstanceEx , anstatt eine einzelne Schnittstelle anzufordern und einen einzelnen Zeiger auf diese Schnittstelle zu erhalten, ein Array von Strukturen anzugeben, die jeweils bei der Eingabe auf einen Schnittstellenbezeichner (IID) zeigen, und bei der Rückgabe einen Zeiger auf die angeforderte Schnittstelle und den Rückgabewert des QueryInterface-Aufrufs für diese Schnittstelle enthält (falls verfügbar). Dies ermöglicht weniger Roundtrips zwischen Computern.

Diese Funktion kapselt drei Aufrufe: zuerst an CoGetClassObject, um eine Verbindung mit dem Klassenobjekt herzustellen, das der angegebenen CLSID zugeordnet ist, wobei der Speicherort der Klasse angegeben wird. zweitens zu IClassFactory::CreateInstance, um eine nicht initialisierte instance zu erstellen, und schließlich zu IClassFactory::Release, um das Klassenobjekt freizugeben.

Das so erstellte Objekt muss weiterhin durch einen Aufruf einer der Initialisierungsschnittstellen (z . B. IPersistStorage::Load) initialisiert werden. Zwei Funktionen, CoGetInstanceFromFile und CoGetInstanceFromIStorage, kapseln sowohl die instance Erstellung als auch die Initialisierung aus den offensichtlichen Quellen.

Die als pServerInfo-Parameter übergebene COSERVERINFO-Struktur enthält die Sicherheitseinstellungen, die COM beim Erstellen einer neuen instance des angegebenen Objekts verwendet. Beachten Sie, dass dieser Parameter die Sicherheitseinstellungen nicht beeinflusst, die beim Ausführen von Methodenaufrufen für das instanziierte Objekt verwendet werden. Diese Sicherheitseinstellungen können auf Schnittstellenbasis mit der CoSetProxyBlanket-Funktion konfiguriert werden. Siehe auch IClientSecurity::SetBlanket.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	combaseapi.h (include Objbase.h)
Bibliothek	Ole32.lib
DLL	Ole32.dll

Weitere Informationen

CoGetInstanceFromFile

CoGetInstanceFromIStorage

Freigeben über