CoCreateInstance-Funktion (combaseapi.h)

Artikel
08/22/2023

Erstellt und initialisiert standardmäßig ein einzelnes Objekt der Klasse, die einer angegebenen CLSID zugeordnet ist.

Rufen Sie CoCreateInstance auf, wenn Sie nur ein Objekt auf dem lokalen System erstellen möchten. Um ein einzelnes Objekt auf einem Remotesystem zu erstellen, rufen Sie die CoCreateInstanceEx-Funktion auf. Um mehrere Objekte basierend auf einer einzelnen CLSID zu erstellen, rufen Sie die CoGetClassObject-Funktion auf.

Syntax

HRESULT CoCreateInstance(
  [in]  REFCLSID  rclsid,
  [in]  LPUNKNOWN pUnkOuter,
  [in]  DWORD     dwClsContext,
  [in]  REFIID    riid,
  [out] LPVOID    *ppv
);

Parameter

[in] rclsid

Die CLSID, die den Daten und dem Code zugeordnet ist, die zum Erstellen des Objekts verwendet werden.

[in] pUnkOuter

Wenn NULL, gibt an, dass das Objekt nicht als Teil eines Aggregats erstellt wird. Wenn nicht NULL, zeiger auf die IUnknown-Schnittstelle des Aggregatobjekts (das steuernde IUnknown).

[in] dwClsContext

Kontext, in dem der Code, der das neu erstellte Objekt verwaltet, ausgeführt wird. Die Werte werden der CLSCTX-Enumeration entnommen.

[in] riid

Ein Verweis auf den Bezeichner der Schnittstelle, die für die Kommunikation mit dem -Objekt verwendet werden soll.

[out] ppv

Adresse der Zeigervariable, die den in riid angeforderten Schnittstellenzeiger empfängt. Nach erfolgreicher Rückgabe enthält *ppv den angeforderten Schnittstellenzeiger. Bei einem Fehler enthält *ppvNULL.

Rückgabewert

Diese Funktion kann die folgenden Werte zurückgeben.

Rückgabecode	BESCHREIBUNG
S_OK	Ein instance der angegebenen Objektklasse wurde erfolgreich erstellt.
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.
E_NOINTERFACE	Die angegebene Klasse implementiert die angeforderte Schnittstelle nicht, oder das steuernde IUnknown macht die angeforderte Schnittstelle nicht verfügbar.
E_POINTER	Der ppv-Parameter ist NULL.

Hinweise

Die CoCreateInstance-Funktion bietet eine praktische Verknüpfung, indem eine Verbindung mit dem Klassenobjekt hergestellt wird, das der angegebenen CLSID zugeordnet ist, ein standardmäßig initialisiertes instance erstellt und das Klassenobjekt freigegeben wird. Daher kapselt es die folgende Funktionalität:

CoGetClassObject(rclsid, dwClsContext, NULL, IID_IClassFactory, &pCF); 
hresult = pCF->CreateInstance(pUnkOuter, riid, ppvObj);
pCF->Release();

Es ist praktisch, CoCreateInstance zu verwenden, wenn Sie nur eine einzelne instance eines Objekts auf dem lokalen Computer erstellen müssen. Wenn Sie eine instance auf einem Remotecomputer erstellen, rufen Sie CoCreateInstanceEx auf. Wenn Sie mehrere Instanzen erstellen, ist es effizienter, einen Zeiger auf die IClassFactory-Schnittstelle des Klassenobjekts abzurufen und die zugehörigen Methoden nach Bedarf zu verwenden. Im letzteren Fall sollten Sie die CoGetClassObject-Funktion verwenden.

In der CLSCTX-Enumeration können Sie den Typ des Servers angeben, der zum Verwalten des Objekts verwendet wird. Die Konstanten können CLSCTX_INPROC_SERVER, CLSCTX_INPROC_HANDLER, CLSCTX_LOCAL_SERVER, CLSCTX_REMOTE_SERVER oder eine beliebige Kombination dieser Werte sein. Die Konstante CLSCTX_ALL wird als Kombination aller vier definiert. Weitere Informationen zur Verwendung einer oder einer Kombination dieser Konstanten finden Sie unter CLSCTX.

UWP-Anwendungen

Obwohl es keine Einschränkungen für CLSIDs gibt, die eine UWP-Anwendung an CoCreateInstance übergeben kann, schlagen viele Objekte mit E_ACCESSDENIED aus Sicherheitsgründen fehl, insbesondere wenn sie nicht während des Prozesses ausgeführt werden. Auch wenn Sie ein Objekt erfolgreich erstellen können, kann es zu einem späteren Zeitpunkt aufgrund von UWP-Sicherheitseinschränkungen, App-Modellunterschieden usw. fehlschlagen. Insbesondere sollten Hintergrundaufgaben die Objekte einschränken, mit denen sie kommunizieren, um Hängerungen oder andere Komplikationen aufgrund verbundener Stand-by-Verbindungen zu vermeiden.

Beispiele

// Create WIC factory
hr = CoCreateInstance(
    CLSID_WICImagingFactory,
    NULL,
    CLSCTX_INPROC_SERVER,
    IID_PPV_ARGS(&m_pIWICFactory)
    );

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