Função OleInitialize (ole2.h)

  • Artigo

Inicializa a biblioteca COM no apartamento atual, identifica o modelo de simultaneidade como STA (apartamento de thread único) e permite funcionalidade adicional descrita na seção Comentários abaixo. Os aplicativos devem inicializar a biblioteca COM antes de poderem chamar funções de biblioteca COM diferentes de CoGetMalloc e funções de alocação de memória.

Sintaxe

HRESULT OleInitialize(
  [in] LPVOID pvReserved
);

Parâmetros

[in] pvReserved

Esse parâmetro é reservado e deve ser NULL.

Retornar valor

Essa função retorna S_OK com êxito. Outros valores possíveis incluem o seguinte.

Código de retorno Descrição
S_FALSE
 A biblioteca COM já está inicializada neste apartamento.
OLE_E_WRONGCOMPOBJ
 As versões de COMPOBJ.DLL e OLE2.DLL em seu computador são incompatíveis entre si.
RPC_E_CHANGED_MODE
 Uma chamada anterior para CoInitializeEx especificou o modelo de simultaneidade para esse apartamento como MTA (multithread apartment). Isso também pode significar que ocorreu uma mudança de apartamento com thread neutro para apartamento único encadeado.

Comentários

Os aplicativos que usam a seguinte funcionalidade devem chamar OleInitialize antes de chamar qualquer outra função na biblioteca COM:

  • Área de Transferência
  • Arrastar e soltar
  • OLE (vinculação e inserção de objeto)
  • Ativação in-loco
OleInitialize chama CoInitializeEx internamente para inicializar a biblioteca COM no apartamento atual. Como as operações OLE não são thread-safe, o OleInitialize especifica o modelo de simultaneidade como apartment de thread único.

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

Você precisa inicializar a biblioteca COM em um apartment 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.

Normalmente, a biblioteca COM é inicializada em um apartamento apenas uma vez. As chamadas subsequentes serão bem-sucedidas, desde que não tentem alterar o modelo de simultaneidade do apartamento, mas retornarão S_FALSE. Para fechar a biblioteca COM normalmente, cada chamada bem-sucedida para OleInitialize, incluindo aquelas que retornam S_FALSE, deve ser balanceada por uma chamada correspondente para OleUninitialize.

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

Requisitos

Requisito Valor
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 ole2.h
Biblioteca Ole32.lib
DLL Ole32.dll
Conjunto de APIs ext-ms-win-com-ole32-l1-1-0 (introduzido em Windows 8)

Confira também

Coinitializeex

Oleinitialize

OleUninitialize