CoGetClassObject-Funktion (combaseapi.h)

Artikel
08/22/2023

Stellt einen Zeiger auf eine Schnittstelle für ein Klassenobjekt bereit, das einer angegebenen CLSID zugeordnet ist. CoGetClassObject sucht den ausführbaren Code, der hierfür erforderlich ist, und lädt ihn bei Bedarf dynamisch.

Rufen Sie CoGetClassObject direkt auf, um mehrere Objekte über ein Klassenobjekt zu erstellen, für das in der Systemregistrierung eine CLSID vorhanden ist. Sie können auch ein Klassenobjekt von einem bestimmten Remotecomputer abrufen. Die meisten Klassenobjekte implementieren die IClassFactory-Schnittstelle . Anschließend rufen Sie CreateInstance auf, um ein nicht initialisiertes Objekt zu erstellen. Es ist jedoch nicht immer notwendig, diesen Prozess zu durchlaufen. Um ein einzelnes Objekt zu erstellen, rufen Sie die CoCreateInstanceEx-Funktion auf, mit der Sie eine instance auf einem Remotecomputer erstellen können. Dadurch wird die CoCreateInstance-Funktion ersetzt, die weiterhin zum Erstellen einer instance auf einem lokalen Computer verwendet werden kann. Beide Funktionen kapseln eine Verbindung mit dem Klassenobjekt, erstellen die instance und geben das Klassenobjekt frei. Zwei weitere Funktionen, CoGetInstanceFromFile und CoGetInstanceFromIStorage, bieten sowohl instance Erstellung auf einem Remotesystem als auch die Objektaktivierung. Es gibt zahlreiche Funktionen und Schnittstellenmethoden, deren Zweck darin besteht, Objekte eines einzelnen Typs zu erstellen und einen Zeiger auf eine Schnittstelle für dieses Objekt bereitzustellen.

Syntax

HRESULT CoGetClassObject(
  [in]           REFCLSID rclsid,
  [in]           DWORD    dwClsContext,
  [in, optional] LPVOID   pvReserved,
  [in]           REFIID   riid,
  [out]          LPVOID   *ppv
);

Parameter

[in] rclsid

Die CLSID, die den Daten und dem Code zugeordnet ist, die Sie zum Erstellen der Objekte verwenden.

[in] dwClsContext

Der Kontext, in dem der ausführbare Code ausgeführt werden soll. Um eine Remoteaktivierung zu aktivieren, schließen Sie CLSCTX_REMOTE_SERVER ein. Weitere Informationen zu den Kontextwerten und deren Verwendung finden Sie in der CLSCTX-Enumeration .

[in, optional] pvReserved

Ein Zeiger auf den Computer, auf dem das Klassenobjekt instanziieren soll. Wenn dieser Parameter NULL ist, wird das Klassenobjekt gemäß der Interpretation des dwClsCtx-Parameters auf dem aktuellen Computer oder auf dem Computer instanziiert, der unter dem RemoteServerName-Schlüssel der Klasse angegeben ist. Weitere Informationen finden Sie unter COSERVERINFO.

[in] riid

Verweis auf den Bezeichner der Schnittstelle, der bei erfolgreicher Rückgabe in ppv angegeben wird. Diese Schnittstelle wird für die Kommunikation mit dem Klassenobjekt verwendet. In der Regel ist dieser Wert IID_IClassFactory, obwohl andere Werte wie IID_IClassFactory2, die eine Form der Lizenzierung unterstützen, zulässig sind. Alle DURCH OLE definierten Schnittstellen-IIDs werden in den OLE-Headerdateien als IID_interfacename definiert, wobei interfacename der Name der Schnittstelle ist.

[out] ppv

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

Rückgabewert

Diese Funktion kann die folgenden Werte zurückgeben.

Rückgabecode	BESCHREIBUNG
S_OK	Speicherort und Verbindung mit dem angegebenen Klassenobjekt waren erfolgreich.
REGDB_E_CLASSNOTREG	Die CLSID ist nicht ordnungsgemäß registriert. Dieser Fehler kann auch darauf hinweisen, dass der in dwClsContext angegebene Wert nicht in der Registrierung enthalten ist.
E_NOINTERFACE	Entweder das Objekt, auf das ppv verweist, unterstützt die durch riid identifizierte Schnittstelle nicht, oder der QueryInterface-Vorgang für das klassenobjekt, das E_NOINTERFACE zurückgegeben wurde.
REGDB_E_READREGDB	Fehler beim Lesen der Registrierungsdatenbank.
CO_E_DLLNOTFOUND	Entweder die Prozess-DLL oder die Handler-DLL wurde nicht gefunden (abhängig vom Kontext).
CO_E_APPNOTFOUND	Die ausführbare Datei (.exe) wurde nicht gefunden (nur CLSCTX_LOCAL_SERVER).
E_ACCESSDENIED	Beim Laden ist ein allgemeiner Zugriffsfehler aufgetreten.
CO_E_ERRORINDLL	Das ausführbare Image enthält einen Fehler.
CO_E_APPDIDNTREG	Die ausführbare Datei wurde gestartet, aber das Klassenobjekt wurde nicht registriert (und es wurde möglicherweise heruntergefahren).

Hinweise

Ein Klassenobjekt in OLE ist ein Zwischenobjekt, das eine Schnittstelle unterstützt, die Vorgänge zulässt, die für eine Gruppe von Objekten gemeinsam sind. Die Objekte in dieser Gruppe sind Instanzen, die von derselben Objektdefinition abgeleitet sind, die durch eine einzelne CLSID dargestellt wird. In der Regel ist die für ein Klassenobjekt implementierte Schnittstelle IClassFactory, über die Sie Objektinstanzen einer bestimmten Definition (Klasse) erstellen können.

Ein Aufruf von CoGetClassObject erstellt, initialisiert und gewährt dem Aufrufer Zugriff (über einen Zeiger auf eine schnittstelle, die mit dem riid-Parameter angegeben ist) auf das Klassenobjekt. Das Klassenobjekt ist das objekt, das der CLSID zugeordnet ist, die Sie im rclsid-Parameter angeben. Die Details, wie das System den zugeordneten Code und die Daten innerhalb eines Computers findet, sind für den Aufrufer transparent, ebenso wie das dynamische Laden von Code, der noch nicht geladen wurde.

Wenn der Klassenkontext CLSCTX_REMOTE_SERVER ist, was angibt, dass eine Remoteaktivierung erforderlich ist, können Sie mit der im Parameter pServerInfobereitgestellten COSERVERINFO-Struktur den Computer angeben, auf dem sich der Server befindet. Informationen zum Algorithmus, der zum Suchen eines Remoteservers verwendet wird, wenn pServerInfoNULL ist, finden Sie in der CLSCTX-Enumeration .

Es gibt zwei Orte, um eine CLSID für eine Klasse zu finden:

Die Registrierung enthält eine Zuordnung zwischen CLSIDs und Dateisuffixen sowie zwischen CLSIDs und Dateisignaturen zum Bestimmen der Klasse eines Objekts.
Wenn ein Objekt im persistenten Speicher gespeichert wird, wird seine CLSID zusammen mit seinen Daten gespeichert.

Um eingebettete oder verknüpfte OLE-Dokumentobjekte zu erstellen und zu initialisieren, ist es nicht erforderlich, CoGetClassObject direkt aufzurufen. Rufen Sie stattdessen die XXX-Funktion OleCreate oder OleCreate auf. Diese Funktionen kapseln den gesamten Instanziierungs- und Initialisierungsprozess des Objekts und rufen neben anderen Funktionen CoGetClassObject auf.

Der riid-Parameter gibt die Schnittstelle an, die der Client für die Kommunikation mit dem Klassenobjekt verwendet. In den meisten Fällen ist diese Schnittstelle IClassFactory. Dies bietet Zugriff auf die CreateInstance-Methode , über die der Aufrufer dann ein nicht initialisiertes Objekt der in der Implementierung angegebenen Art erstellen kann. Alle klassen, die im System mit einer CLSID registriert sind, müssen IClassFactory implementieren.

In seltenen Fällen können Sie jedoch eine andere Schnittstelle angeben, die Vorgänge definiert, die für eine Gruppe von Objekten gemeinsam sind. In der Art und Weise, wie OLE Moniker implementiert, lautet die Schnittstelle für das Klassenobjekt beispielsweise IParseDisplayName, das zum Transformieren des Anzeigenamens eines Objekts in einen Moniker verwendet wird.

Der dwClsContext-Parameter gibt den Ausführungskontext an, sodass eine CLSID verschiedenen Codeteilen in verschiedenen Ausführungskontexten zugeordnet werden kann. Die CLSCTX-Enumeration gibt die verfügbaren Kontextflags an. CoGetClassObject ruft (entsprechend dem angegebenen Kontext) sowohl die Registrierung als auch die Klassenobjekte ab, die derzeit durch Aufrufen der CoRegisterClassObject-Funktion registriert sind.

Verwenden Sie die Release-Methode des Klassenobjekts, um ein Klassenobjekt freizugeben. Die Funktion CoRevokeClassObject darf nur verwendet werden, um die CLSID eines Klassenobjekts aus der Systemregistrierung zu entfernen.

Anforderungen


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