OleCreateEx-Funktion (ole2.h)

Artikel
08/25/2023

Erweitert die OleCreate-Funktionalität , indem eine effizientere Instanziierung von Objekten in Containern unterstützt wird, die das Zwischenspeichern mehrerer Präsentationsformate oder Daten anstelle des einzelnen von OleCreate unterstützten Formats erfordern.

Syntax

HRESULT OleCreateEx(
  [in]  REFCLSID        rclsid,
  [in]  REFIID          riid,
  [in]  DWORD           dwFlags,
  [in]  DWORD           renderopt,
  [in]  ULONG           cFormats,
  [in]  DWORD           *rgAdvf,
  [in]  LPFORMATETC     rgFormatEtc,
  [in]  IAdviseSink     *lpAdviseSink,
  [out] DWORD           *rgdwConnection,
  [in]  LPOLECLIENTSITE pClientSite,
  [in]  LPSTORAGE       pStg,
  [out] LPVOID          *ppvObj
);

Parameter

[in] rclsid

Gibt die Klasse des zu erstellenden Objekts an.

[in] riid

Verweis auf den Bezeichner der Schnittstelle des zurückzugebenden Objekts.

[in] dwFlags

Dieser Wert kann 0 oder OLECREATE_LEAVERUNNING (0x00000001) sein.

[in] renderopt

Wert aus der OLERENDER-Enumeration .

[in] cFormats

Wenn renderopt OLERENDER_FORMAT ist, gibt die Anzahl der FORMATETC-Strukturen im rgFormatEtc-Array an, die mindestens eine sein muss. In allen anderen Fällen muss dieser Parameter 0 sein.

[in] rgAdvf

Wenn renderopt OLERENDER_FORMAT ist, verweist auf ein Array von cFormats-DWORD-Elementen, die jeweils eine Kombination von Werten aus der ADVF-Enumeration sind. Jedes Element dieses Arrays wird als advf-Parameter an einen Aufruf von IOleCache::Cache oder IDataObject::D Advise übergeben, je nachdem, ob pAdviseSinkNULL oder nicht NULL ist (siehe unten). In allen anderen Fällen muss dieser Parameter NULL sein.

[in] rgFormatEtc

Wenn renderopt OLERENDER_FORMAT ist, zeigt auf ein Array von cFormats FORMATETC-Strukturen . Wenn pAdviseSinkNULL ist, wird jedes Element dieses Arrays als pFormatEtc-Parameter an einen Aufruf des IOleCache::Cache des Objekts übergeben. Dadurch wird der Vom Prozesshandler für Objekte verwaltete Daten- und Präsentationscache (in der Regel der Standardhandler) mit Präsentations- oder anderen zwischenspeicherbaren Daten aufgefüllt. Wenn pAdviseSink nicht NULL ist, wird jedes Element dieses Arrays als pFormatEtc-Parameter an einen Aufruf von IDataObject::D Advise übergeben. Dadurch kann der Aufrufer (in der Regel ein OLE-Container) eine eigene Zwischenspeicherung oder Verarbeitung der vom Objekt empfangenen Daten durchführen. In allen anderen Fällen muss dieser Parameter NULL sein.

[in] lpAdviseSink

Wenn renderopt OLERENDER_FORMAT ist, kann es sich entweder um einen gültigen IAdviseSink-Zeiger handelt, der die benutzerdefinierte Zwischenspeicherung oder Verarbeitung von Datenhinweisen angibt, oder NULL, der die Standardzwischenspeicherung von Datenformaten angibt. In allen anderen Fällen muss dieser Parameter NULL sein.

[out] rgdwConnection

Speicherort zum Zurückgeben des Arrays der dwConnection-Werte , die zurückgegeben werden, wenn die pAdviseSink-Schnittstelle für jede Advisory-Verbindung mit IDataObject::D Advise registriert ist, oder NULL , wenn die zurückgegebenen Beratungsverbindungen nicht benötigt werden. Muss NULL sein, wenn pAdviseSinkNULL ist.

[in] pClientSite

Zeiger auf die primäre Schnittstelle, über die das Objekt Dienste von seinem Container anfordern wird. Dieser Parameter kann NULL sein. In diesem Fall liegt es in der Verantwortung des Aufrufers, den Clientstandort so schnell wie möglich mithilfe von IOleObject::SetClientSite einzurichten.

[in] pStg

Zeiger auf den Speicher, der für das Objekt verwendet werden soll, und auf alle dafür eingerichteten Standarddaten- oder Präsentationszwischenspeicherung. Dieser Parameter ist möglicherweise nicht NULL.

[out] ppvObj

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

Rückgabewert

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

Rückgabecode	Beschreibung
E_NOINTERFACE	Der angegebene Schnittstellenbezeichner ist ungültig.

Hinweise

Der folgende Aufruf von OleCreate:

OleCreate(rclsid, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

entspricht dem folgenden Aufruf von OleCreateEx:

DWORD    advf = ADVF_PRIMEFIRST;
    OleCreateEx(rclsid, riid, renderopt, 1, &amp;advf, pFormatEtc, NULL, pClientSite, pStg, ppvObj);

Vorhandene Instanziierungsfunktionen (OleCreate, OleCreateFromFile, OleCreateFromData, OleCreateLink , OleCreateLinkToFile und OleCreateLinkFromData) erstellen während der Instanziierung nur einen einzelnen Präsentations- oder Datenformatcache im Standardcachespeicherort (innerhalb der Streams "\001OlePresXXX" der übergebenen IStorage). Außerdem müssen diese Caches erstellt werden, wenn das Objekt als nächstes in den Ausführungszustand wechselt. Da die meisten Anwendungen mindestens zwei Präsentationen (Bildschirm und Drucker) zwischenspeichern müssen und möglicherweise Daten in einem anderen Format oder Speicherort als der Handler zwischenspeichern müssen, müssen Anwendungen den Objektserver in der Regel mehrmals starten und herunterfahren, um ihre Datencaches während der Objekterstellung aufzulisten, d. h. Objekt einfügen, Objekt aus Datei einfügen und Objekt einfügen.

Erweiterte Versionen dieser Erstellungsfunktionen lösen dieses Problem. OleCreateEx, OleCreateFromFileEx, OleCreateFromDataEx, OleCreateLinkEx, OleCreateLinkToFileEx und OleCreateLinkFromDataEx enthalten die folgenden neuen Parameter: dwFlags zum Angeben zusätzlicher Optionen, cFormats , um anzugeben, wie viele Formate zwischengespeichert werden sollen, rgAdvf aus der ADVF-Enumeration , um die Empfehlungsflags für jedes zu zwischenspeichernde Format anzugeben, pAdviseSink um anzugeben, ob die Zwischenspeicherung von Präsentationen (Standardhandler) oder Daten (nicht standardmäßiger Handler) erforderlich ist, gibt rgdwConnectionIDataObject::D Advise-Cookies zurück, und pFormatEtc, ein Array von Formaten anstelle eines einzelnen Formats.

Container, die erfordern, dass mehrere Präsentationen in ihrem Namen vom Handler des Objekts zwischengespeichert werden müssen, können einfach diese Funktionen aufrufen und die Anzahl der Formate in cFormats, die ADVF-Flags für jedes Format in rgAdvf und den Satz von Formaten in pFormatEtc angeben. Diese Container übergeben NULL für pAdviseSink.

Container, die alle ihre eigenen Daten- oder Präsentationszwischenspeicherungen ausführen, führen die gleichen Schritte aus, übergeben jedoch eine pAdviseSink-Instanz ohne NULL. Sie führen während IAdviseSink::OnDataChange ihre eigene Zwischenspeicherung oder Bearbeitung des Objekts oder der Daten durch. In der Regel stellen solche Container nie die Beratungsverbindungen mit ADVF_NODATA her, obwohl dies nicht verhindert wird.

Diese neuen Funktionen gelten für OLE Compound Documents. Mithilfe dieser Funktionen können Anwendungen die von den aktuellen Funktionen erforderlichen wiederholten Start- und Initialisierungsschritte vermeiden. Sie richten sich an OLE Compound Document-Containeranwendungen, die standardbasierte Daten- und Präsentationszwischenspeicherung verwenden, sowie für Anwendungen, die ihre eigene Zwischenspeicherung und Datenübertragung von der zugrunde liegenden IDataObject::D Advise-Unterstützung bereitstellen.

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