Função CoInitialize (objbase.h)

Inicializa a biblioteca COM no thread atual e identifica o modelo de simultaneidade como STA (single-thread apartment).

Novos aplicativos devem chamar CoInitializeEx em vez de CoInitialize.

Se você quiser usar o Windows Runtime, chame RoInitialize ou Windows::Foundation::Initialize.

Sintaxe

HRESULT CoInitialize(
  [in, optional] LPVOID pvReserved
);

Parâmetros

[in, optional] pvReserved

Esse parâmetro é reservado e deve ser NULL.

Valor retornado

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

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.

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.

CoInitializeEx fornece a mesma funcionalidade que CoInitialize e também fornece um parâmetro para especificar explicitamente o modelo de simultaneidade do thread. CoInitialize chama CoInitializeEx e especifica o modelo de simultaneidade como apartment de thread único. Os aplicativos desenvolvidos hoje devem chamar CoInitializeEx em vez de CoInitialize.

Normalmente, a biblioteca COM é inicializada em um thread apenas uma vez. As chamadas subsequentes para CoInitialize ou CoInitializeEx no mesmo thread terão êxito, desde que não tentem alterar o modelo de simultaneidade, mas retornarão S_FALSE. Para fechar a biblioteca COM normalmente, cada chamada bem-sucedida para CoInitialize ou CoInitializeEx, incluindo aquelas que retornam S_FALSE, deve ser balanceada por uma chamada correspondente para CoUninitialize. No entanto, o primeiro thread no aplicativo que chama CoInitialize com 0 (ou CoInitializeEx com COINIT_APARTMENTTHREADED) deve ser o último thread a chamar CoUninitialize. Caso contrário, as chamadas subsequentes para CoInitialize no STA falharão e o aplicativo não funcionará.

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

Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	objbase.h
Biblioteca	Ole32.lib
DLL	Ole32.dll
Conjunto de APIs	ext-ms-win-com-sta-l1-1-0 (introduzido no Windows 10, versão 10.0.20166)

Confira também

Coinitializeex