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 |
|---|---|
|
A biblioteca COM foi inicializada com êxito nesse thread. |
|
A biblioteca COM já está inicializada nesse thread. |
|
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) |