Funzione OleCreateLinkEx (ole2.h)

Articolo
02/29/2024

Estende la funzionalità OleCreateLink supportando la creazione di istanze più efficienti di oggetti nei contenitori che richiedono la memorizzazione nella cache di più formati di presentazioni o dati, anziché il formato singolo supportato da OleCreateLink.

Sintassi

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
);

Parametri

[in] pmkLinkSrc

Puntatore a un moniker all'oggetto a cui creare un collegamento.

[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 ottenuto dall'enumerazione OLERENDER .

[in] cFormats

Quando renderopt è 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 renderopt è 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. In questo modo i dati e la cache delle presentazioni vengono popolati dal gestore in-process degli oggetti (in genere il gestore predefinito) con presentazione o altri dati memorizzabili nella cache. Quando pAdviseSink non è NULL, ogni elemento di questa matrice viene passato come parametro pFormatEtc a una chiamata a IDataObject::D Advise. In questo modo il chiamante (in genere un contenitore OLE) può eseguire la propria memorizzazione nella cache o l'elaborazione dei dati ricevuti dall'oggetto.

[in] lpAdviseSink

Quando renderopt è OLERENDER_FORMAT, può essere un puntatore IAdviseSink valido, che indica la memorizzazione nella cache o l'elaborazione personalizzata dei dati consiglia o NULL, che indica la memorizzazione nella cache predefinita dei formati di dati.

[out] rgdwConnection

Posizione in cui restituire la matrice di valori dwConnection restituiti quando l'interfaccia IAdviseSink viene registrata per ogni connessione consultiva tramite IDataObject::D Advise o NULL se le connessioni consultive 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 appena possibile usando IOleObject::SetClientSite.

[in] pStg

Puntatore alla risorsa di archiviazione da usare per l'oggetto ed eventuali dati predefiniti o memorizzazione nella cache delle presentazioni stabiliti.

[out] ppvObj

Indirizzo della variabile del puntatore di output che riceve il puntatore di interfaccia richiesto in riid. Al termine della restituzione, *ppvObj contiene il puntatore di 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
E_NOINTERFACE	L'identificatore di interfaccia specificato non è valido.
E_INVALIDARG	Uno o più parametri non sono validi.

Commenti

La chiamata seguente a OleCreateLink:

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

equivale alla chiamata seguente a OleCreateLinkEx:

DWORD    advf = ADVF_PRIMEFIRST;
    OleCreateFromFileEx(pmkLinkSrc, 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 cache di presentazione o formato dati nel percorso di cache predefinito (all'interno dei flussi '\001OlePresXXX' dei flussi IStorage passati) durante la creazione di istanze. Inoltre, queste cache devono essere create quando l'oggetto successivo entra nello stato di esecuzione. Poiché la maggior parte delle applicazioni richiede la memorizzazione nella cache in almeno due presentazioni (schermata e stampante) e potrebbe richiedere la memorizzazione nella cache dei dati in un formato o un percorso diverso dal gestore, le applicazioni devono in genere avviare e arrestare il server oggetti più volte per prime le cache dei dati durante la creazione dell'oggetto, ad esempio Insert Object, Insert Object from File, e Incolla oggetto .

Le versioni estese di queste funzioni di creazione risolvono questo problema. OleCreateEx, OleCreateFromFileEx, OleCreateFromDataEx, OleCreateLinkEx, OleCreateLinkToFileEx e OleCreateLinkFromDataEx, contengono i nuovi parametri seguenti: dwFlags per indicare opzioni aggiuntive, cFormats per indicare quanti formati memorizzare nella cache, rgAdvf, dall'enumerazione ADVF , per specificare i flag consigliati per ogni formato da memorizzare nella cache, pAdviseSink per indicare se la memorizzazione nella cache della presentazione (gestore predefinito) o dei dati (non default-handler) è necessaria, rgdwConnection per restituire i cookie IDataObject::D Advise e rgFormatEtc, una matrice di formati anziché un unico formato.

I contenitori che richiedono che più presentazioni vengano memorizzate nella cache per loro conto dal 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 pAdviseSink diverso da NULL. Eseguono la propria 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 vengono impedite di farlo.

Queste nuove funzioni sono per i documenti composti OLE. Usando queste funzioni, le applicazioni possono evitare i passaggi ripetuti di avvio e inizializzazione richiesti dalle funzioni correnti. Sono destinati ad applicazioni contenitore di documenti composti OLE che usano i dati predefiniti e la memorizzazione nella cache delle presentazioni e anche alle applicazioni che forniscono la propria memorizzazione nella cache e il trasferimento dei dati dal supporto IDataObject::D Advise sottostante .

Requisiti

Requisito	Valore
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