OleCreateFromDataEx-Funktion (ole2.h)

Artikel
03/06/2024

Erweitert die OleCreateFromData-Funktionalität , indem eine effizientere Instanziierung von Objekten in Containern unterstützt wird, die die Zwischenspeicherung mehrerer Präsentations- oder Datenformate anstelle des einzelnen Von OleCreateFromData unterstützten Formats erfordern.

Syntax

HRESULT OleCreateFromDataEx(
  [in]  LPDATAOBJECT    pSrcDataObj,
  [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] pSrcDataObj

Zeiger auf das Datenübertragungsobjekt mit den neuen Daten, die zum Erstellen des neuen Objekts verwendet werden. (siehe OleCreateFromData).

[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 0 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, zeigt auf ein Array von FORMATETC-Strukturen . Wenn pAdviseSinkNULL ist, wird jedes Element dieses Arrays als pFormatEtc-Parameter an einen Aufruf des IOleCache::Cache des Objekts übergeben. Dadurch werden die Daten und der Präsentationscache, der vom Prozesshandler des Objekts (in der Regel der Standardhandler) verwaltet wird, 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] lpAdviseSink

Wenn renderopt OLERENDER_FORMAT ist, kann es sich entweder um einen gültigen IAdviseSink-Zeiger , 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 Advisory-Verbindung mit IDataObject::D Advise registriert ist, 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 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.

[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.
E_INVALIDARG	Mindestens ein Parameter ist ungültig.

Hinweise

Der folgende Aufruf von OleCreateFromData:

OleCreateFromData(lpszFileName, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

entspricht dem folgenden Aufruf von OleCreateFromDataEx:

DWORD    advf = ADVF_PRIMEFIRST;
    OleCreateFromFileEx(rclsid, lpszFileName, riid, renderopt, 1, &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 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 primen, 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 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, die erfordern, dass mehrere Präsentationen in ihrem Namen vom Handler des Objekts zwischengespeichert werden müssen, können diese Funktionen einfach 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 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 sie nicht daran gehindert werden.

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