Funzione CoInitializeEx (combaseapi.h)

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

È consigliabile chiamare Windows::Foundation::Initialize per inizializzare il thread anziché CoInitializeEx se si desidera usare le API di Windows Runtime o se si desidera usare sia i componenti COM che 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

Opzioni di concorrenza e inizializzazione per il thread. I valori per questo parametro vengono acquisiti dall'enumerazione COINIT . Qualsiasi combinazione di valori da COINIT può essere usata, ad eccezione del fatto che i flag di COINIT_APARTMENTTHREADED e COINIT_MULTITHREADED non possono essere impostati entrambi. 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.

Codice restituito	Descrizione
S_OK	La libreria COM è stata inizializzata correttamente in questo thread.
S_FALSE	La libreria COM è già inizializzata in questo thread.
RPC_E_CHANGED_MODE	Una chiamata precedente a CoInitializeEx ha specificato il modello di concorrenza per questo thread come appartamento multithread (MTA). Ciò potrebbe anche indicare che si è verificato un cambiamento da appartamento con thread neutrale a appartamento a thread singolo.

Commenti

CoInitializeEx deve essere chiamato almeno una volta e viene in genere chiamato una sola volta per ogni thread che usa la libreria COM. Più chiamate a CoInitializeEx dallo stesso thread sono consentite purché passino lo stesso flag di concorrenza, ma le chiamate valide successive restituiscono S_FALSE. Per chiudere correttamente la libreria COM su 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.

È necessario inizializzare la libreria COM in un thread prima di chiamare una delle funzioni di libreria tranne 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.

Dopo aver impostato il modello di concorrenza per un thread, non può essere modificato. Una chiamata a CoInitialize su un appartamento inizializzato in precedenza come multithreaded avrà esito negativo e restituirà RPC_E_CHANGED_MODE.

Gli oggetti creati in un appartamento a thread singolo (STA) ricevono chiamate solo dal thread dell'appartamento, 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 appartamento multithread (MTA) devono essere in grado di ricevere chiamate di metodo da altri thread in qualsiasi momento. In genere si implementerebbe una forma di controllo di concorrenza nel codice di un oggetto multithreading usando primitive di sincronizzazione, ad esempio sezioni critiche, semafori o mutex per proteggere i dati dell'oggetto.

Quando un oggetto configurato per l'esecuzione nell'appartamento con thread neutrale (NTA) viene chiamato da un thread che si trova in una sta o nell'MTA, tale thread passa 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 di COINIT_APARTMENTTHREADED. Di conseguenza, un appartamento inizializzato per la concorrenza a 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, CoInitializeEx o CoUninitialize dalla funzione DllMain.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [app desktop | App UWP]
Server minimo supportato	Windows 2000 Server [app desktop | App UWP]
Piattaforma di destinazione	Windows
Intestazione	combaseapi.h (include Objbase.h)
Libreria	Ole32.lib
DLL	Ole32.dll

Vedi anche

Processi, thread e appartamenti