Função CoCreateInstanceEx (combaseapi.h)

Cria uma instância de uma classe específica em um computador específico.

Sintaxe

HRESULT CoCreateInstanceEx(
  [in]      REFCLSID     Clsid,
  [in]      IUnknown     *punkOuter,
  [in]      DWORD        dwClsCtx,
  [in]      COSERVERINFO *pServerInfo,
  [in]      DWORD        dwCount,
  [in, out] MULTI_QI     *pResults
);

Parâmetros

[in] Clsid

O CLSID do objeto a ser criado.

[in] punkOuter

Se esse parâmetro não for NULL, indicará que a instância está sendo criada como parte de uma agregação e punkOuter será usado como O IUnknown controlador da nova instância. Atualmente, não há suporte para agregação entre processos ou entre computadores. Ao instanciar um objeto fora do processo, CLASS_E_NOAGGREGATION será retornado se punkOuter não for NULL.

[in] dwClsCtx

Um valor da enumeração CLSCTX .

[in] pServerInfo

Informações sobre o computador no qual instanciar o objeto. Consulte COSERVERINFO. Esse parâmetro pode ser NULL, caso em que o objeto é instanciado no computador local ou no computador especificado no registro sob o valor RemoteServerName da classe, de acordo com a interpretação do parâmetro dwClsCtx .

[in] dwCount

O número de estruturas em pResults. Esse valor deve ser maior que 0.

[in, out] pResults

Uma matriz de estruturas MULTI_QI . Cada estrutura tem três membros: o identificador de uma interface solicitada (pIID), o local para retornar o ponteiro da interface (pItf) e o valor retornado da chamada para QueryInterface (hr).

Retornar valor

Essa função pode retornar o valor retornado padrão E_INVALIDARG, bem como os valores a seguir.

Código de retorno	Descrição
S_OK	Indica ê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 que 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.
CO_S_NOTALLINTERFACES	Pelo menos uma, mas nem todas as interfaces solicitadas na matriz pResults foram recuperadas com êxito. O membro hr de cada uma das estruturas de MULTI_QI em pResults indica com S_OK ou E_NOINTERFACE se a interface específica foi retornada.
E_NOINTERFACE	Nenhuma das interfaces solicitadas na matriz pResults foi recuperada com êxito.

Comentários

CoCreateInstanceEx cria um único objeto não inicializado associado ao CLSID fornecido em um computador remoto especificado. Essa é uma extensão da função CoCreateInstance, que cria apenas um objeto no computador local. Além disso, em vez de solicitar uma única interface e obter um único ponteiro para essa interface, CoCreateInstanceEx possibilita especificar uma matriz de estruturas, cada uma apontando para um identificador de interface (IID) na entrada e, no retorno, contendo (se disponível) um ponteiro para a interface solicitada e o valor retornado da chamada QueryInterface para essa interface. Isso permite menos viagens de ida e volta entre computadores.

Essa função encapsula três chamadas: primeiro, para CoGetClassObject para se conectar ao objeto de classe associado ao CLSID especificado, especificando o local da classe; second, to IClassFactory::CreateInstance to create an uninitialized instance, and finally, to IClassFactory::Release, to release the class object.

O objeto assim criado ainda deve ser inicializado por meio de uma chamada para uma das interfaces de inicialização (como IPersistStorage::Load). Duas funções, CoGetInstanceFromFile e CoGetInstanceFromIStorage encapsulam a criação e a inicialização da instância das fontes óbvias.

A estrutura COSERVERINFO passada como o parâmetro pServerInfo contém as configurações de segurança que o COM usará ao criar uma nova instância do objeto especificado. Observe que esse parâmetro não influencia as configurações de segurança usadas ao fazer chamadas de método no objeto instanciado. Essas configurações de segurança são configuráveis, por interface, com a função CoSetProxyBlanket . Consulte também IClientSecurity::SetBlanket.

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

Confira também

CoGetInstanceFromFile

CoGetInstanceFromIStorage