Função CoCreateInstance (combaseapi.h)

Artigo
08/22/2023

Cria e inicializa um único objeto da classe associada a um CLSID especificado.

Chame CoCreateInstance quando quiser criar apenas um objeto no sistema local. Para criar um único objeto em um sistema remoto, chame a função CoCreateInstanceEx . Para criar vários objetos com base em um único CLSID, chame a função CoGetClassObject .

Sintaxe

HRESULT CoCreateInstance(
  [in]  REFCLSID  rclsid,
  [in]  LPUNKNOWN pUnkOuter,
  [in]  DWORD     dwClsContext,
  [in]  REFIID    riid,
  [out] LPVOID    *ppv
);

Parâmetros

[in] rclsid

O CLSID associado aos dados e ao código que serão usados para criar o objeto.

[in] pUnkOuter

Se NULL, indica que o objeto não está sendo criado como parte de uma agregação. Se não for NULL, ponteiro para a interface IUnknown do objeto agregado (o IUnknown controlador).

[in] dwClsContext

Contexto em que o código que gerencia o objeto recém-criado executará. Os valores são obtidos da enumeração CLSCTX.

[in] riid

Uma referência ao identificador da interface a ser usada para se comunicar com o objeto .

[out] ppv

Endereço da variável de ponteiro que recebe o ponteiro de interface solicitado em riid. Após o retorno bem-sucedido, *ppv contém o ponteiro de interface solicitado. Após a falha, *ppv contém NULL.

Retornar valor

Essa função pode retornar os valores a seguir.

Código de retorno	Descrição
S_OK	Uma instância da classe de objeto especificada foi criada com êxito.
REGDB_E_CLASSNOTREG	Uma classe especificada não está registrada no banco de dados de registro. Também pode indicar que o tipo de servidor solicitado na enumeração CLSCTX não está registrado ou os valores dos tipos de servidor no registro estão corrompidos.
CLASS_E_NOAGGREGATION	Essa classe não pode ser criada como parte de uma agregação.
E_NOINTERFACE	A classe especificada não implementa a interface solicitada ou o IUnknown controlador não expõe a interface solicitada.
E_POINTER	O parâmetro ppv é NULL.

Comentários

A função CoCreateInstance fornece um atalho conveniente conectando-se ao objeto de classe associado ao CLSID especificado, criando uma instância inicializada padrão e liberando o objeto de classe. Dessa forma, ele encapsula a seguinte funcionalidade:

CoGetClassObject(rclsid, dwClsContext, NULL, IID_IClassFactory, &pCF); 
hresult = pCF->CreateInstance(pUnkOuter, riid, ppvObj);
pCF->Release();

É conveniente usar CoCreateInstance quando você precisa criar apenas uma única instância de um objeto no computador local. Se você estiver criando uma instância no computador remoto, chame CoCreateInstanceEx. Quando você está criando várias instâncias, é mais eficiente obter um ponteiro para a interface IClassFactory do objeto de classe e usar seus métodos conforme necessário. No último caso, você deve usar a função CoGetClassObject .

Na enumeração CLSCTX , você pode especificar o tipo de servidor usado para gerenciar o objeto. As constantes podem ser CLSCTX_INPROC_SERVER, CLSCTX_INPROC_HANDLER, CLSCTX_LOCAL_SERVER, CLSCTX_REMOTE_SERVER ou qualquer combinação desses valores. A CLSCTX_ALL constante é definida como a combinação de todos os quatro. Para obter mais informações sobre o uso de uma ou uma combinação dessas constantes, consulte CLSCTX.

Aplicativos UWP

Embora não haja restrições sobre quais CLSIDs um aplicativo UWP pode passar para CoCreateInstance, muitos objetos falharão com E_ACCESSDENIED por motivos de segurança, especialmente se não forem executados em processo. Além disso, mesmo que você possa criar um objeto com êxito, ele poderá falhar posteriormente devido a restrições de segurança UWP, diferenças de modelo de aplicativo etc. Em particular, as tarefas em segundo plano devem limitar os objetos com os quais se comunicam para evitar travamentos ou outras complicações devido ao stand-by conectado.

Exemplos

// Create WIC factory
hr = CoCreateInstance(
    CLSID_WICImagingFactory,
    NULL,
    CLSCTX_INPROC_SERVER,
    IID_PPV_ARGS(&m_pIWICFactory)
    );

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	combaseapi.h (inclua Objbase.h)
Biblioteca	Ole32.lib
DLL	Ole32.dll