Funzione OleCreateLinkFromDataEx (ole2.h)
Estende la funzionalità OleCreateLinkFromData supportando un'istanza più efficiente degli oggetti nei contenitori che richiedono la memorizzazione nella cache di più formati di presentazioni o dati, anziché il singolo formato supportato da OleCreateLinkFromData.
Sintassi
HRESULT OleCreateLinkFromDataEx(
[in] LPDATAOBJECT pSrcDataObj,
[in] REFIID riid,
[in] DWORD dwFlags,
[in] DWORD renderopt,
[in] ULONG cFormats,
[in] DWORD *rgAdvf,
[in] LPFORMATETC rgFormatEtc,
[in] IAdviseSink *lpAdviseSink,
[in, out] DWORD *rgdwConnection,
[in] LPOLECLIENTSITE pClientSite,
[in] LPSTORAGE pStg,
[out] LPVOID *ppvObj
);
Parametri
[in] pSrcDataObj
Puntatore all'oggetto dati da cui creare un oggetto link.
[in] riid
Riferimento all'identificatore dell'interfaccia dell'oggetto da restituire.
[in] dwFlags
Questo parametro può essere 0 o OLECREATE_LEAVERUNNING (0x00000001).
[in] renderopt
Valore tratto dall'enumerazione OLERENDER .
[in] cFormats
Quando il rendering è OLERENDER_FORMAT, indica il numero di strutture FORMATETC nella matrice rgFormatEtc , che deve essere almeno uno. In tutti gli altri casi, questo parametro deve essere zero.
[in] rgAdvf
Quando il rendering è OLERENDER_FORMAT, punta a una matrice di elementi DWORD , ognuno dei quali è una combinazione di valori dell'enumerazione ADVF . Ogni elemento di questa matrice viene passato come parametro advf a una chiamata a IOleCache::Cache o IDataObject::D Advise, a seconda che pAdviseSink sia NULL o non NULL (vedere di seguito). In tutti gli altri casi, questo parametro deve essere NULL.
[in] rgFormatEtc
Quando il rendering è OLERENDER_FORMAT, punta a una matrice di strutture FORMATETC . Quando pAdviseSink è NULL, ogni elemento di questa matrice viene passato come parametro pFormatEtc a una chiamata all'oggetto IOleCache::Cache. Questo popola i dati e la cache di presentazione gestiti dal gestore in-process degli oggetti (in genere il gestore predefinito) con presentazione o altri dati memorizzati nella cache. Quando pAdviseSink non è NULL, ogni elemento di questa matrice viene passato come parametro pFormatEtc a una chiamata a IDataObject::D Advise. Ciò consente al chiamante (in genere un contenitore OLE) di eseguire la memorizzazione nella cache o l'elaborazione dei dati ricevuti dall'oggetto.
[in] lpAdviseSink
Quando il rendering è OLERENDER_FORMAT, può essere un puntatore IAdviseSink valido, che indica la memorizzazione nella cache o l'elaborazione dei dati personalizzati o NULL, che indica la memorizzazione nella cache predefinita dei formati di dati.
[in, out] rgdwConnection
Posizione per restituire la matrice di valori dwConnection restituiti quando l'interfaccia pAdviseSink viene registrata per ogni connessione consultiva usando IDataObject::D Advise o NULL se le connessioni di consulenza restituite non sono necessarie. Questo parametro deve essere NULL se pAdviseSink è NULL.
[in] pClientSite
Puntatore all'interfaccia primaria tramite cui l'oggetto richiederà i servizi dal contenitore. Questo parametro può essere NULL, nel qual caso è responsabilità del chiamante stabilire il sito client non appena possibile usando IOleObject::SetClientSite.
[in] pStg
Puntatore all'archiviazione da usare per l'oggetto e per qualsiasi dati o memorizzazione nella cache delle presentazioni predefinite stabilita.
[out] ppvObj
Indirizzo della variabile del puntatore di output che riceve il puntatore dell'interfaccia richiesto in riid. Al termine della restituzione, *ppvObj contiene il puntatore dell'interfaccia richiesto nell'oggetto appena creato.
Valore restituito
Questa funzione restituisce S_OK in caso di esito positivo. Altri valori possibili includono quanto segue.
| Codice restituito | Descrizione |
|---|---|
|
L'identificatore dell'interfaccia specificato non è valido. |
|
Uno o più parametri non sono validi. |
Commenti
La chiamata seguente a OleCreateLinkFromData:
OleCreateLinkFromData(pSrcDataObj, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);
equivale alla chiamata seguente a OleCreateLinkFromDataEx:
DWORD advf = ADVF_PRIMEFIRST;
OleCreateLinkFromDataEx(pSrcDataObj, riid, renderopt, 1, &advf, pFormatEtc, NULL, NULL, pClientSite, pStg, ppvObj);
Le funzioni di creazione di istanze esistenti (OleCreate, OleCreateFromFile, OleCreateFromData, OleCreateLink, OleCreateLinkToFile e OleCreateLinkFromData), creano solo una singola presentazione o cache del formato dati nel percorso della cache predefinita (all'interno dei flussi '\001OlePresXXX' dei flussi IStorage passati) durante l'istanza. Inoltre, queste cache devono essere create quando l'oggetto entra nello stato in esecuzione. Poiché la maggior parte delle applicazioni richiede la memorizzazione nella cache almeno due presentazioni (schermata e stampante) e può richiedere la memorizzazione nella cache dei dati in un formato o una posizione diversa dal gestore, le applicazioni devono in genere avviare e arrestare più volte il server oggetti per primetare le cache dei dati durante la creazione di oggetti, ad esempio Insert Object, Insert Object from File e Paste Object.
Le versioni estese di queste funzioni di creazione risolveranno questo problema. OleCreateEx, OleCreateFromFileEx, OleCreateFromDataEx, OleCreateLinkEx, OleCreateLinkToFileEx e OleCreateLinkFromDataEx, contengono i nuovi parametri seguenti: dwFlags per indicare opzioni aggiuntive, cFormats per indicare il numero di formati da memorizzare nella cache, rgAdvf, dall'enumerazione ADVF, per specificare i flag consigliati per ogni formato da memorizzare nella cache, pAdviseSink per indicare se la presentazione (gestore predefinito) o i dati (gestore non predefinito) di memorizzazione nella cache sono necessari, rgdwConnection per restituire i cookie IDataObject::D Advise e rgFormatEtc, una matrice di formati anziché un singolo formato.
I contenitori che richiedono la memorizzazione nella cache di più presentazioni per conto del gestore dell'oggetto possono semplicemente chiamare queste funzioni e specificare il numero di formati in cFormats, i flag ADVF per ogni formato in rgAdvf e il set di formati in rgFormatEtc. Questi contenitori passano NULL per pAdviseSink.
I contenitori che eseguono tutti i propri dati o la memorizzazione nella cache delle presentazioni eseguono questi stessi passaggi, ma passano un valore pAdviseSink diverso da NULL. Eseguono la memorizzazione nella cache o la manipolazione dell'oggetto o dei dati durante IAdviseSink::OnDataChange. In genere tali contenitori non stabiliscono mai le connessioni consultive con ADVF_NODATA, anche se non sono impedite di farlo.
Queste nuove funzioni sono per i documenti composti OLE. Usando queste funzioni, le applicazioni possono evitare i passaggi di avvio e inizializzazione ripetuti richiesti dalle funzioni correnti. Sono destinati alle applicazioni contenitore di documenti composti OLE che usano i dati predefiniti e la memorizzazione nella cache delle presentazioni, nonché alle applicazioni che forniscono la propria memorizzazione nella cache e il trasferimento dei dati dal supporto IDataObject::D Advise sottostante .
Requisiti
| Client minimo supportato | Windows 2000 Professional [solo app desktop] |
| Server minimo supportato | Windows 2000 Server [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | ole2.h |
| Libreria | Ole32.lib |
| DLL | Ole32.dll |