Funzione CoInitializeEx (combaseapi.h)

Inizializza la libreria COM da utilizzare dal thread chiamante, imposta il modello di concorrenza del thread e crea un nuovo apartment per il thread, se necessario.

Devi chiamare Windows::Foundation::Initialize per inizializzare il thread anziché CoInitializeEx se vuoi usare le API di Windows Runtime o se vuoi usare componenti COM e Windows Runtime. Windows::Foundation::Initialize è sufficiente per l'uso per i componenti COM.

Sintassi

HRESULT CoInitializeEx(
  [in, optional] LPVOID pvReserved,
  [in]           DWORD  dwCoInit
);

Parametri

[in, optional] pvReserved

Questo parametro è riservato e deve essere NULL.

[in] dwCoInit

Il modello di concorrenza e le opzioni di inizializzazione per il thread. I valori per questo parametro vengono ricavati dall'enumerazione COINIT. È possibile utilizzare qualsiasi combinazione di valori di COINIT, ad eccezione del fatto che i flag COINIT_APARTMENTTHREADED e COINIT_MULTITHREADED non possono essere entrambi impostati. Il valore predefinito è COINIT_MULTITHREADED.

Valore restituito

Questa funzione può restituire i valori restituiti standard E_INVALIDARG, E_OUTOFMEMORY e E_UNEXPECTED, nonché i valori seguenti.

Osservazioni

CoInitializeEx deve essere chiamato almeno una volta e viene in genere chiamato una sola volta per ogni thread che usa la libreria COM. Sono consentite più chiamate a CoInitializeEx dallo stesso thread, purché passino lo stesso flag di concorrenza, ma le chiamate valide successive restituiscono S_FALSE. Se il flag di concorrenza non corrisponde, la chiamata ha esito negativo e restituisce RPC_E_CHANGED_MODE. Ai fini di questa regola, una chiamata a CoInitialize equivale a chiamare CoInitializeEx con il flag COINIT_APARTMENTTHREADED. Per inizializzare normalmente la libreria COM in un thread, ogni chiamata riuscita a CoInitialize o CoInitializeEx, inclusa qualsiasi chiamata che restituisce S_FALSE, deve essere bilanciata da una chiamata corrispondente a CoUninitialize. Dopo aver inizializzato COM in un thread, è possibile reinizializzare in qualsiasi modalità, soggetto ai vincoli precedenti.

È necessario inizializzare la libreria COM in un thread prima di chiamare una delle funzioni di libreria ad eccezione di CoGetMalloc, per ottenere un puntatore all'allocatore standard e alle funzioni di allocazione della memoria. In caso contrario, la funzione COM restituirà CO_E_NOTINITIALIZED.

Gli oggetti creati in un apartment a thread singolo (STA) ricevono chiamate al metodo solo dal thread del proprio apartment, quindi le chiamate vengono serializzate e arrivano solo ai limiti della coda di messaggi (quando viene chiamata la funzione PeekMessage o SendMessage).

Gli oggetti creati in un thread COM in un apartment multithread (MTA) devono essere in grado di ricevere chiamate di metodo da altri thread in qualsiasi momento. In genere si implementa una forma di controllo della concorrenza nel codice di un oggetto multithreading usando primitive di sincronizzazione come sezioni critiche, semafori o mutex per proteggere i dati dell'oggetto.

Quando un oggetto configurato per l'esecuzione nell'apartment a thread neutro (NTA) viene chiamato da un thread che si trova in una sta o in un MTA, tale thread viene trasferita all'NTA. Se questo thread chiama successivamente CoInitializeEx, la chiamata ha esito negativo e restituisce RPC_E_CHANGED_MODE.

Poiché le tecnologie OLE non sono thread-safe, la funzione OleInitialize chiama CoInitializeEx con il flag COINIT_APARTMENTTHREADED. Di conseguenza, un apartment inizializzato per la concorrenza di oggetti multithreading non può usare le funzionalità abilitate da OleInitialize.

Poiché non è possibile controllare l'ordine in cui i server in-process vengono caricati o scaricati, non chiamare CoInitialize, CoInitializeExo CoUninitialize dalla funzione DllMain .

Fabbisogno

Vedere anche

processi, thread e appartamenti