Funzione OleCreateEmbeddingHelper (ole2.h)

Articolo
03/15/2023

Crea un oggetto helper di incorporamento OLE utilizzando il codice fornito dall'applicazione aggregato con parti del gestore oggetti predefinito OLE. Questo oggetto helper può essere creato e usato in un contesto e in un ruolo specifico, come determinato dal chiamante.

Sintassi

HRESULT OleCreateEmbeddingHelper(
  [in]  REFCLSID       clsid,
  [in]  LPUNKNOWN      pUnkOuter,
  [in]  DWORD          flags,
  [in]  LPCLASSFACTORY pCF,
  [in]  REFIID         riid,
  [out] LPVOID         *lplpObj
);

Parametri

[in] clsid

CLSID della classe da aiutare.

[in] pUnkOuter

Se l'helper di incorporamento deve essere aggregato, puntatore all'interfaccia IUnknown di controllo dell'oggetto esterno. Se non deve essere aggregato, anche se questo è raro, il valore deve essere NULL.

[in] flags

DWORD contenente flag che specificano il ruolo e il contesto di creazione per l'helper di incorporamento. Per i valori legali, vedere la sezione Osservazioni seguente.

[in] pCF

Puntatore all'interfaccia IClassFactory nell'oggetto classe utilizzata dalla funzione per creare l'oggetto secondario. In alcune situazioni, questo valore può essere NULL. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[in] riid

Riferimento all'identificatore dell'interfaccia desiderata dal chiamante.

[out] lplpObj

Indirizzo della variabile del puntatore che riceve il puntatore di interfaccia richiesto in riid. Al termine della restituzione, *ppvObj contiene il puntatore di interfaccia richiesto nell'helper di incorporamento appena creato.

Valore restituito

Questa funzione restituisce S_OK in caso di esito positivo. Altri valori possibili includono quanto segue.

Codice restituito	Descrizione
E_OUTOFMEMORY	Memoria insufficiente per l'operazione.
E_INVALIDARG	Uno o più parametri non sono validi.
E_UNEXPECTED	Si è verificato un errore imprevisto.
E_NOINTERFACE	L'identificatore di interfaccia specificato non è valido.

Commenti

La funzione OleCreateEmbeddingHelper crea un oggetto che supporta le stesse implementazioni di interfaccia presenti nel gestore predefinito, ma con hook aggiuntivi che consentono di usarlo più in genere di un oggetto gestore. Le due chiamate seguenti producono lo stesso risultato:

OleCreateEmbeddingHelper(clsid, pUnkOuter, EMBDHLP_INPROC_HANDLER | 
    EMBDHLP_CREATENOW, NULL, iid, ppvObj) 
 
OleCreateDefaultHandler(clsid, pUnkOuter, iid, ppvObj)

L'helper di incorporamento è aggregabile; pUnkOuter è il controllo IUnknown dell'aggregazione di cui deve essere parte l'helper di incorporamento. Viene usato per creare una nuova istanza del gestore predefinito OLE, che può essere usato per supportare gli oggetti in vari ruoli. Il chiamante passa un puntatore all'implementazione IClassFactory a OleCreateEmbeddingHelper. Questo oggetto e il gestore predefinito vengono quindi aggregati per creare il nuovo oggetto helper di incorporamento.

La funzione OleCreateEmbeddingHelper viene in genere usata per supportare una delle implementazioni seguenti:

Applicazione oggetto EXE usata sia come contenitore che come server e che supporta l'inserimento di oggetti in se stesso. Per questo caso , CreateEmbeddingHelper consente all'oggetto di supportare le interfacce in genere supportate solo nel gestore. A tale scopo, l'applicazione deve prima registrare il relativo CLSID per contesti diversi, effettuando due chiamate di registrazione alla funzione CoRegisterClassObject , anziché una, come indicato di seguito:
```
CoRegisterClassObject(clsidMe, pUnkCfLocal, CLSCTX_LOCAL_SERVER, 
        REGCLS_MULTI_SEPARATE...) 
 
    CoRegisterClassObject(clsidMe, pUnkCfInProc, CLSCTX_INPROC_SERVER, 
    
        REGCLS_MULTI_SEPARATE...) 
```
In queste chiamate si passano diverse implementazioni di class factory a ognuna di pUnkCfLocal e pUnkCfInProc. La class factory a cui punta pUnkCfLocal verrebbe usata per creare oggetti che devono essere incorporati in un processo remoto, ovvero il caso normale che usa un oggetto gestore associato al client. Tuttavia, quando un server crea un oggetto e lo incorpora all'interno di se stesso, pUnkCfInProc punta a un oggetto classe in grado di creare un oggetto che supporta le interfacce del gestore. La classe locale viene usata per creare l'oggetto e la classe in-process crea l'helper di incorporamento, passando il puntatore alla class factory del primo oggetto in pCF.
Un gestore di oggetti in-process personalizzato, nel qual caso la DLL crea l'helper di incorporamento passando un puntatore a un'implementazione privata di IClassFactory in pCF.

Il parametro flags indica come usare l'helper di incorporamento e come e quando viene inizializzato l'helper di incorporamento. I valori per i flag vengono ottenuti tramite OR-ing insieme i valori della tabella seguente.

Valori per il parametro flags	Scopo
EMBDHLP_INPROC_HANDLER	Crea un helper di incorporamento che può essere usato con applicazioni di oggetti DLL; in particolare, l'helper espone le funzionalità di memorizzazione nella cache del gestore oggetti predefinito.
EMBDHLP_INPROC_SERVER	Crea un helper di incorporamento da utilizzare come parte di un server in-process. pCF non può essere NULL.
EMBDHLP_CREATENOW	Crea l'oggetto secondario usando immediatamente pCF ; se pCF è NULL, viene usato il gestore proxy standard.
EMBDHLP_DELAYCREATE	Ritarda la creazione dell'oggetto secondario fino a quando non è necessario (quando l'helper viene inserito nello stato di esecuzione) per migliorare la velocità e l'uso della memoria. pCF non deve essere NULL. Il flag EMBDHLP_INPROC_HANDLER non può essere utilizzato con questo flag.

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
Set di API	ext-ms-win-com-ole32-l1-1-5 (introdotto in Windows 10, versione 10.0.15063)

Vedi anche

OleCreateDefaultHandler

Condividi tramite