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.

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

Confira também

CoGetInstanceFromFile

CoGetInstanceFromIStorage