OleCreateEmbeddingHelper-Funktion (ole2.h)

  • Artikel

Erstellt ein OLE-Einbettungshilfsobjekt mithilfe von von der Anwendung bereitgestelltem Code, der mit Teilen des OLE-Standardobjekthandlers aggregiert ist. Dieses Hilfsobjekt kann erstellt und in einem bestimmten Kontext und einer bestimmten Rolle verwendet werden, wie vom Aufrufer festgelegt.

Syntax

HRESULT OleCreateEmbeddingHelper(
  [in]  REFCLSID       clsid,
  [in]  LPUNKNOWN      pUnkOuter,
  [in]  DWORD          flags,
  [in]  LPCLASSFACTORY pCF,
  [in]  REFIID         riid,
  [out] LPVOID         *lplpObj
);

Parameter

[in] clsid

CLSID der zu helfenden Klasse.

[in] pUnkOuter

Wenn das Einbettungshilfsprogramm aggregiert werden soll, zeiger auf die steuernde IUnknown-Schnittstelle des äußeren Objekts. Wenn es nicht aggregiert werden soll, obwohl dies selten ist, sollte der Wert NULL sein.

[in] flags

DWORD mit Flags, die die Rolle und den Erstellungskontext für das Einbettungshilfsprogramm angeben. Informationen zu rechtlichen Werten finden Sie im folgenden Abschnitt hinweise.

[in] pCF

Zeiger auf die IClassFactory-Schnittstelle für das Klassenobjekt, das die Funktion zum Erstellen des sekundären Objekts verwendet. In einigen Situationen kann dieser Wert NULL sein. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in] riid

Verweis auf den Bezeichner der Vom Aufrufer gewünschten Schnittstelle.

[out] lplpObj

Adresse der Zeigervariablen, die den in riid angeforderten Schnittstellenzeiger empfängt. Nach erfolgreicher Rückgabe enthält *ppvObj den angeforderten Schnittstellenzeiger für das neu erstellte Einbettungshilfsprogramm.

Rückgabewert

Diese Funktion gibt S_OK nach Erfolg zurück. Weitere mögliche Werte sind:

Rückgabecode Beschreibung
E_OUTOFMEMORY
 Unzureichender Arbeitsspeicher für den Vorgang.
E_INVALIDARG
Mindestens ein Parameter ist ungültig.
E_UNEXPECTED
 Ein unerwarteter Fehler ist aufgetreten.
E_NOINTERFACE
 Der angegebene Schnittstellenbezeichner ist ungültig.

Hinweise

Die OleCreateEmbeddingHelper-Funktion erstellt ein -Objekt, das die gleichen Schnittstellenimplementierungen unterstützt, die im Standardhandler enthalten sind, aber über zusätzliche Hooks verfügt, mit denen es allgemeiner als nur als Handlerobjekt verwendet werden kann. Die folgenden beiden Aufrufe führen zu demselben Ergebnis:

OleCreateEmbeddingHelper(clsid, pUnkOuter, EMBDHLP_INPROC_HANDLER | 
    EMBDHLP_CREATENOW, NULL, iid, ppvObj) 
 
OleCreateDefaultHandler(clsid, pUnkOuter, iid, ppvObj)

Das Einbettungshilfsprogramm ist aggregierbar; pUnkOuter ist das steuernde IUnknown des Aggregats, zu dem das Einbettungshilfsprogramm gehören soll. Sie wird verwendet, um eine neue instance des OLE-Standardhandlers zu erstellen, der zur Unterstützung von Objekten in verschiedenen Rollen verwendet werden kann. Der Aufrufer übergibt einen Zeiger an seine IClassFactory-Implementierung an OleCreateEmbeddingHelper. Dieses Objekt und der Standardhandler werden dann aggregiert, um das neue Einbettungshilfsobjekt zu erstellen.

Die OleCreateEmbeddingHelper-Funktion wird in der Regel verwendet, um eine der folgenden Implementierungen zu unterstützen:

  • Eine EXE-Objektanwendung, die sowohl als Container als auch als Server verwendet wird und das Einfügen von Objekten in sich selbst unterstützt. In diesem Fall ermöglicht CreateEmbeddingHelper , dass das Objekt die Schnittstellen unterstützt, die normalerweise nur im Handler unterstützt werden. Um dies zu erreichen, muss die Anwendung zunächst ihre CLSID für verschiedene Kontexte registrieren und zwei Registrierungsaufrufe an die CoRegisterClassObject-Funktion statt eines wie folgt ausführen:
    CoRegisterClassObject(clsidMe, pUnkCfLocal, CLSCTX_LOCAL_SERVER, 
        REGCLS_MULTI_SEPARATE...) 
 
    CoRegisterClassObject(clsidMe, pUnkCfInProc, CLSCTX_INPROC_SERVER, 
    
        REGCLS_MULTI_SEPARATE...)

    In diesen Aufrufen würden Sie verschiedene Klassenfactoryimplementierungen an jede von pUnkCfLocal und pUnkCfInProc übergeben. Die Klassenfactory, auf die von pUnkCfLocal verwiesen wird, wird verwendet, um Objekte zu erstellen, die in einen Remoteprozess eingebettet werden sollen. Dies ist der Normalfall, der ein dem Client zugeordnetes Handlerobjekt verwendet. Wenn ein Server jedoch sowohl ein Objekt erstellt als auch in sich selbst einbettet, verweist pUnkCfInProc auf ein Klassenobjekt, das ein Objekt erstellen kann, das die Handlerschnittstellen unterstützt. Die lokale Klasse wird verwendet, um das Objekt zu erstellen, und die In-Process-Klasse erstellt das Einbettungshilfsprogramm und übergibt den Zeiger auf die Klassenfactory des ersten Objekts in pCF.

  • Ein benutzerdefinierter prozessinterner Objekthandler. In diesem Fall erstellt die DLL das Einbettungshilfsprogramm, indem sie einen Zeiger an eine private Implementierung von IClassFactory in pCF übergibt.
Der Flags-Parameter gibt an, wie das Einbettungshilfsprogramm verwendet werden soll und wie und wann das Einbettungshilfsprogramm initialisiert wird. Die Werte für Flags werden durch or-inging-Werte aus der folgenden Tabelle abgerufen.
Werte für flags-Parameter Zweck
EMBDHLP_INPROC_HANDLER Erstellt ein Einbettungshilfsprogramm, das mit DLL-Objektanwendungen verwendet werden kann. Insbesondere macht das Hilfsprogramm die Zwischenspeicherungsfeatures des Standardobjekthandlers verfügbar.
EMBDHLP_INPROC_SERVER Erstellt ein Einbettungshilfsprogramm, das als Teil eines Prozessservers verwendet werden soll. pCF darf nicht NULL sein.
EMBDHLP_CREATENOW Erstellt das sekundäre Objekt sofort mithilfe von pCF . Wenn pCF NULL ist, wird der Standardproxy-Manager verwendet.
EMBDHLP_DELAYCREATE Verzögert die Erstellung des sekundären Objekts, bis es benötigt wird (wenn das Hilfsprogramm in den Ausführungszustand versetzt wird), um die Geschwindigkeit und die Speicherauslastung zu verbessern. pCF darf nicht NULL sein. Das EMBDHLP_INPROC_HANDLER-Flag kann nicht mit diesem Flag verwendet werden.

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 ole2.h
Bibliothek Ole32.lib
DLL Ole32.dll
APIs ext-ms-win-com-ole32-l1-1-5 (eingeführt in Windows 10, Version 10.0.15063)

Weitere Informationen

OleCreateDefaultHandler