Função CoCreateInstance (combaseapi.h)

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.

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

Confira também

Cocreateinstanceex

Cogetclassobject

IClassFactory::CreateInstance

Funções auxiliares de criação de instância