Funzione OleCreateEx (ole2.h)

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

Sintassi

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

Identifica la classe dell'oggetto da creare.

[in] riid

Riferimento all'identificatore dell'interfaccia dell'oggetto da restituire.

[in] dwFlags

Questo valore 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 cFormats, 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 cFormats. 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 tutti gli altri casi, questo parametro deve essere NULL.

[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 tutti gli altri casi, questo parametro deve essere NULL.

[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. 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. Questo parametro potrebbe non essere NULL.

[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.

Commenti

La chiamata seguente a OleCreate:

OleCreate(rclsid, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

equivale alla chiamata seguente a OleCreateEx:

DWORD    advf = ADVF_PRIMEFIRST;
    OleCreateEx(rclsid, riid, renderopt, 1, &advf, pFormatEtc, NULL, pClientSite, pStg, ppvObj);

Funzioni di creazione di istanze esistenti, (OleCreate, OleCreateFromFile, OleCreateFromData, OleCreateLink, OleCreateLinkToFile e OleCreateLinkFromData) creano solo una singola presentazione o una 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 memorizzazione nella cache (gestore predefinito) o dati (gestore non predefinito) è necessaria, rgdwConnection per restituire i cookie IDataObject::D Advise e pFormatEtc, 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 pFormatEtc. 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

Vedi anche

ADVF

FORMATETC

IAdviseSink::OnDataChange

IDataObject::D Advise

IOleCache::Cache

IOleObject::SetClientSite

IStorage

OLERENDER

OleCreate