Função CoInitializeEx (combaseapi.h)

Inicializa a biblioteca COM para uso pelo thread de chamada, define o modelo de simultaneidade do thread e cria um novo apartment para o thread se for necessário.

Você deve chamar Windows::Foundation::Initialize para inicializar o thread em vez de CoInitializeEx se quiser usar as APIs Windows Runtime ou se quiser usar componentes COM e Windows Runtime. Windows::Foundation::Initialize é suficiente para usar para componentes COM.

Sintaxe

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

Parâmetros

[in, optional] pvReserved

Esse parâmetro é reservado e deve ser NULL.

[in] dwCoInit

O modelo de simultaneidade e as opções de inicialização para o thread. Os valores para esse parâmetro são obtidos da enumeração COINIT . Qualquer combinação de valores de COINIT pode ser usada, exceto que os sinalizadores COINIT_APARTMENTTHREADED e COINIT_MULTITHREADED não podem ser definidos. O padrão é COINIT_MULTITHREADED.

Retornar valor

Essa função pode retornar os valores retornados padrão E_INVALIDARG, E_OUTOFMEMORY e E_UNEXPECTED, bem como os valores a seguir.

Código de retorno	Descrição
S_OK	A biblioteca COM foi inicializada com êxito nesse thread.
S_FALSE	A biblioteca COM já está inicializada nesse thread.
RPC_E_CHANGED_MODE	Uma chamada anterior para CoInitializeEx especificou o modelo de simultaneidade para esse thread como MTA (multithread apartment). Isso também pode indicar que ocorreu uma mudança de apartamento com thread neutro para apartamento de thread único.

Comentários

CoInitializeEx deve ser chamado pelo menos uma vez e geralmente é chamado apenas uma vez, para cada thread que usa a biblioteca COM. Várias chamadas para CoInitializeEx pelo mesmo thread são permitidas desde que passem o mesmo sinalizador de simultaneidade, mas chamadas válidas subsequentes retornam S_FALSE. Para fechar a biblioteca COM normalmente em um thread, cada chamada bem-sucedida para CoInitialize ou CoInitializeEx, incluindo qualquer chamada que retorna S_FALSE, deve ser balanceada por uma chamada correspondente para CoUninitialize.

Você precisa inicializar a biblioteca COM em um thread antes de chamar qualquer uma das funções de biblioteca, exceto CoGetMalloc, para obter um ponteiro para o alocador padrão e as funções de alocação de memória.

Caso contrário, a função COM retornará CO_E_NOTINITIALIZED.

Depois que o modelo de simultaneidade de um thread for definido, ele não poderá ser alterado. Uma chamada para CoInitialize em um apartamento que foi inicializado anteriormente como multithreaded falhará e retornará RPC_E_CHANGED_MODE.

Os objetos criados em um STA (single-threaded apartment) recebem chamadas de método somente do thread do apartamento, portanto, as chamadas são serializadas e chegam apenas aos limites da fila de mensagens (quando a função PeekMessage ou SendMessage é chamada).

Os objetos criados em um thread COM em um MTA (multithread apartment) devem ser capazes de receber chamadas de método de outros threads a qualquer momento. Normalmente, você implementaria alguma forma de controle de simultaneidade no código de um objeto multithread usando primitivos de sincronização, como seções críticas, semáforos ou mutexes para ajudar a proteger os dados do objeto.

Quando um objeto configurado para ser executado no NTA (apartment threaded neutro) é chamado por um thread que está em um STA ou no MTA, esse thread é transferido para a NTA. Se esse thread chamar CoInitializeEx posteriormente, a chamada falhará e retornará RPC_E_CHANGED_MODE.

Como as tecnologias OLE não são thread-safe, a função OleInitialize chama CoInitializeEx com o sinalizador COINIT_APARTMENTTHREADED. Como resultado, um apartment inicializado para simultaneidade de objeto multithread não pode usar os recursos habilitados pelo OleInitialize.

Como não há como controlar a ordem na qual os servidores em processo são carregados ou descarregados, não chame CoInitialize, CoInitializeEx ou CoUninitialize da função DllMain .

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte	Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	combaseapi.h (inclua Objbase.h)
Biblioteca	Ole32.lib
DLL	Ole32.dll

Confira também

Processos, threads e apartamentos