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.

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

Confira também

Processos, threads e apartamentos