Funzione OleCreate (ole2.h)

Articolo
08/25/2023

Crea un oggetto incorporato identificato da un CLSID. In genere viene usato per implementare la voce di menu che consente all'utente finale di inserire un nuovo oggetto.

Sintassi

HRESULT OleCreate(
  [in]  REFCLSID        rclsid,
  [in]  REFIID          riid,
  [in]  DWORD           renderopt,
  [in]  LPFORMATETC     pFormatEtc,
  [in]  LPOLECLIENTSITE pClientSite,
  [in]  LPSTORAGE       pStg,
  [out] LPVOID          *ppvObj
);

Parametri

[in] rclsid

CLSID dell'oggetto incorporato da creare.

[in] riid

Riferimento all'identificatore dell'interfaccia, in genere IID_IOleObject (definito nelle intestazioni OLE come identificatore dell'interfaccia per IOleObject), tramite cui il chiamante comunicherà con il nuovo oggetto.

[in] renderopt

Valore dell'enumerazione OLERENDER, che indica le funzionalità di disegno memorizzate nella cache locale che l'oggetto appena creato deve avere. Il valore OLERENDER scelto influisce sui valori possibili per il parametro pFormatEtc .

[in] pFormatEtc

A seconda di quale flag OLERENDER viene usato come valore di rendering, puntatore a uno dei valori di enumerazione FORMATETC . Per le restrizioni, vedere l'enumerazione OLERENDER . Questo parametro, insieme al parametro renderopt , specifica inizialmente quale nuovo oggetto può memorizzare nella cache.

[in] pClientSite

Se si vuole che OleCreate chiami IOleObject::SetClientSite, puntatore all'interfaccia IOleClientSite nel contenitore. Il valore può essere NULL, nel qual caso è necessario chiamare in modo specifico IOleObject::SetClientSite prima di tentare le operazioni.

[in] pStg

Puntatore a un'istanza dell'interfaccia IStorage nell'oggetto di archiviazione. Questo parametro potrebbe non essere NULL.

[out] ppvObj

Indirizzo della variabile puntatore che riceve il puntatore dell'interfaccia richiesto in riid. Al termine della restituzione, *ppvObject contiene il puntatore dell'interfaccia richiesto.

Valore restituito

Questa funzione restituisce S_OK in caso di esito positivo e supporta il valore restituito standard E_OUTOFMEMORY.

Codice restituito	Descrizione
E_OUTOFMEMORY	Memoria insufficiente per l'operazione.

Commenti

La funzione OleCreate crea un nuovo oggetto incorporato e viene in genere chiamato per implementare la voce di menu Inserisci nuovo oggetto. Quando OleCreate restituisce, l'oggetto creato è vuoto (non contiene dati), a meno che il rendering non sia OLERENDER_DRAW o OLERENDER_FORMAT e viene caricato. I contenitori in genere chiamano la funzione OleRun o IOleObject::D oVerb per visualizzare l'oggetto per la modifica iniziale.

Il parametro rclsid specifica il CLSID dell'oggetto richiesto. I CLSID degli oggetti registrati vengono archiviati nel Registro di sistema. Quando un utente dell'applicazione seleziona Inserisci oggetto, una casella di selezione consente all'utente di selezionare il tipo di oggetto desiderato da quelli del Registro di sistema. Quando OleCreate viene usato per implementare la voce di menu Inserisci oggetto, il CLSID associato all'elemento selezionato viene assegnato al parametro rclsid di OleCreate.

Il parametro riid specifica l'interfaccia che il client userà per comunicare con il nuovo oggetto. Al termine della restituzione, il parametro ppvObject contiene un puntatore all'interfaccia richiesta.

La cache dell'oggetto creato contiene informazioni che consentono una presentazione di un oggetto contenuto quando il contenitore viene aperto. Informazioni su ciò che deve essere memorizzato nella cache vengono passati nei valori renderopt e pFormatetc . Quando OleCreate restituisce, la cache dell'oggetto creato non viene necessariamente riempita. La cache viene invece riempita la prima volta che l'oggetto entra nello stato in esecuzione. Il chiamante può aggiungere un controllo cache aggiuntivo con una chiamata a IOleCache::Cache dopo la restituzione di OleCreate e prima dell'esecuzione dell'oggetto. Se il rendering è OLERENDER_DRAW o OLERENDER_FORMAT, OleCreate richiede che l'oggetto supporti l'interfaccia IOleCache . Non esiste alcun requisito per qualsiasi altro valore di rendering.

Se pClientSite non è NULL, OleCreate chiama IOleObject::SetClientSite tramite il puntatore pClientSite . IOleClientSite è l'interfaccia primaria in base alla quale un oggetto richiede servizi dal contenitore. Se pClientSite è NULL, è necessario effettuare una chiamata specifica a IOleObject::SetClientSite prima di tentare qualsiasi operazione.

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 (include Ole2.h)
Libreria	Ole32.lib
DLL	Ole32.dll

Vedi anche

Condividi tramite