Função CoInitializeEx (combaseapi.h)

Artigo
11/12/2024

Inicializa a biblioteca COM para uso pelo thread de chamada, define o modelo de simultaneidade do thread e cria um novo apartamento 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 do Windows Runtime ou se quiser usar componentes COM e Windows Runtime. Windows::Foundation::Initialize é suficiente para uso 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 desse 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.

Valor de retorno

Essa função pode retornar os valores de retorno 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 neste thread.
S_FALSE	A biblioteca COM já está inicializada neste thread.
RPC_E_CHANGED_MODE	Uma chamada anterior para CoInitializeEx especificava um modelo de simultaneidade incompatível para esse thread. Isso também pode indicar que ocorreu uma alteração de apartamento com thread neutro para apartamento de thread único.

Observações

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. Se o sinalizador de simultaneidade não corresponder, a chamada falhará e retornará RPC_E_CHANGED_MODE. (Para fins dessa regra, uma chamada para CoInitialize é equivalente a chamar CoInitializeEx com o sinalizador COINIT_APARTMENTTHREADED.) Para não inicializar a biblioteca COM normalmente em um thread, cada chamada bem-sucedida para CoInitialize ou CoInitializeEx, incluindo qualquer chamada que retorne S_FALSE, deve ser balanceada por uma chamada correspondente para CoUninitialize. Depois que o COM tiver sido não inicializado em um thread, você poderá reinicializá-lo em qualquer modo, sujeito às restrições acima.

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.

Os objetos criados em um STA (apartamento de thread único) recebem chamadas de método apenas 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 (apartamento multithread) 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 (apartamento com thread neutro) é chamado por um thread que está em um STA ou no MTA, esse thread é transferido para a NTA. Se esse thread posteriormente chamar CoInitializeEx, 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 apartamento inicializado para simultaneidade de objeto multithreaded não pode usar os recursos habilitados por OleInitialize.

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

Requisitos

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

Consulte também

processos, threads e apartamentos

Compartilhar via