OleCreateLinkEx-Funktion (ole2.h)

Artikel
02/29/2024

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

Syntax

HRESULT OleCreateLinkEx(
  [in]  LPMONIKER       pmkLinkSrc,
  [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] pmkLinkSrc

Zeiger auf einen Moniker auf das Objekt, mit dem eine Verknüpfung erstellt werden soll.

[in] riid

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

[in] dwFlags

Dieser Parameter 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 null sein.

[in] rgAdvf

Wenn renderopt OLERENDER_FORMAT ist, verweist auf ein Array von DWORD-Elementen , von denen jedes eine Kombination von Werten aus der ADVF-Enumeration ist. 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, verweist auf ein Array von FORMATTC-Strukturen . Wenn pAdviseSinkNULL ist, wird jedes Element dieses Arrays als pFormatEtc-Parameter an einen Aufruf von IOleCache::Cache des Objekts übergeben. Dadurch werden die Daten und der Präsentationscache, der vom Prozesshandler für Objekte (in der Regel der Standardhandler) verwaltet wird, mit Präsentationsdaten 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) die vom Objekt empfangenen Daten selbst zwischenspeichern oder verarbeiten.

[in] lpAdviseSink

Wenn renderopt OLERENDER_FORMAT ist, kann entweder ein gültiger IAdviseSink-Zeiger sein, der die benutzerdefinierte Zwischenspeicherung oder Verarbeitung von Datenhinweisen angibt, oder NULL, der die Standardzwischenspeicherung von Datenformaten angibt.

[out] rgdwConnection

Speicherort zum Zurückgeben des Arrays von dwConnection-Werten , die zurückgegeben werden, wenn die IAdviseSink-Schnittstelle für jede Empfehlungsverbindung mithilfe von IDataObject::D Advise registriert wird, oder NULL , wenn die zurückgegebenen Beratungsverbindungen nicht benötigt werden. Dieser Parameter muss NULL sein, wenn pAdviseSinkNULL ist.

[in] pClientSite

Zeiger auf die primäre Schnittstelle, über die das Objekt Dienste von seinem Container anfordere. 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, sowie auf alle für dieses Objekt eingerichteten Standarddaten oder Präsentationszwischenspeicherung.

[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 S_OK nach Erfolg zurück. Weitere mögliche Werte sind:

Rückgabecode	Beschreibung
E_NOINTERFACE	Der angegebene Schnittstellenbezeichner ist ungültig.
E_INVALIDARG	Mindestens ein Parameter ist ungültig.

Hinweise

Der folgende Aufruf von OleCreateLink:

OleCreateLink(pmkLinkSrc, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

entspricht dem folgenden Aufruf von OleCreateLinkEx:

DWORD    advf = ADVF_PRIMEFIRST;
    OleCreateFromFileEx(pmkLinkSrc, riid, renderopt, 1, &advf, pFormatEtc, NULL, 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 "\001OlePresXXX"-Streams des ü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 eine Zwischenspeicherung in mindestens zwei Präsentationen (Bildschirm und Drucker) erfordern und daten möglicherweise in einem anderen Format oder Speicherort vom Handler zwischenspeichern müssen, müssen Anwendungen den Objektserver in der Regel mehrmals starten und herunterfahren, um ihre Datencaches während der Objekterstellung zu optimieren, 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 zur Angabe zusätzlicher Optionen, cFormats , um anzugeben, wie viele Formate zwischengespeichert werden sollen, rgAdvf aus der ADVF-Enumeration , um die Empfehlungsflags für jedes zwischengespeicherte 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 rgFormatEtc, ein Array von Formaten anstelle eines einzelnen Formats.

Container, in denen mehrere Präsentationen vom Objekthandler 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 rgFormatEtc 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 einen pAdviseSink ungleich NULL. Sie führen während IAdviseSink::OnDataChange eigene Zwischenspeicherung oder Bearbeitung des Objekts oder der Daten durch. In der Regel stellen solche Container niemals Beratungsverbindungen mit ADVF_NODATA her, obwohl sie daran nicht gehindert werden.

Diese neuen Funktionen gelten für OLE-Verbunddokumente. Mithilfe dieser Funktionen können Anwendungen die wiederholten Start- und Initialisierungsschritte vermeiden, die für die aktuellen Funktionen erforderlich sind. Sie richten sich an OLE Compound Document-Containeranwendungen, die standardmäßige 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