Funzione OleCreateFromFileEx (ole2.h)

Estende la funzionalità OleCreateFromFile supportando un'istanza più efficiente di oggetti nei contenitori che richiedono la memorizzazione nella cache di più formati o dati di presentazione, anziché il formato singolo supportato da OleCreateFromFile.

Sintassi

HRESULT OleCreateFromFileEx(
  [in]  REFCLSID        rclsid,
  [in]  LPCOLESTR       lpszFileName,
  [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] rclsid

Questo parametro è riservato e deve essere CLSID_NULL.

[in] lpszFileName

Puntatore al nome del file da cui deve essere inizializzato il nuovo oggetto.

[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

Percorso per restituire la matrice di valori dwConnection restituiti quando l'interfaccia pAdviseSink 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 il prima 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.

Commenti

La chiamata seguente a OleCreateFromFile:

OleCreateFromFile(rclsid, lpszFileName, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

equivale alla chiamata seguente a OleCreateFromFileEx:

DWORD    advf = ADVF_PRIMEFIRST;
    OleCreateFromFileEx(rclsid, lpszFileName, riid, renderopt, 1, &advf, pFormatEtc, 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 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 di almeno due presentazioni (schermata e stampante) e potrebbe richiedere la memorizzazione nella cache dei dati in un formato o in 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 Paste Object.

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

Vedi anche

ADVF

FORMATETC

IAdviseSink::OnDataChange

IDataObject::D Advise

IOleCache::Cache

IOleObject::SetClientSite

IStorage

OLERENDER

OleCreateFromFile