Função CoGetClassObject (combaseapi.h)

Artigo
08/22/2023

Fornece um ponteiro para uma interface em um objeto de classe associado a um CLSID especificado. CoGetClassObject localiza e, se necessário, carrega dinamicamente o código executável necessário para fazer isso.

Chame CoGetClassObject diretamente para criar vários objetos por meio de um objeto de classe para o qual há um CLSID no registro do sistema. Você também pode recuperar um objeto de classe de um computador remoto específico. A maioria dos objetos de classe implementa a interface IClassFactory . Em seguida, você chamaria CreateInstance para criar um objeto não inicializado. No entanto, nem sempre é necessário passar por esse processo. Para criar um único objeto, chame a função CoCreateInstanceEx , que permite criar uma instância em um computador remoto. Isso substitui a função CoCreateInstance , que ainda pode ser usada para criar uma instância em um computador local. Ambas as funções encapsulam a conexão com o objeto de classe, a criação da instância e a liberação do objeto de classe. Duas outras funções, CoGetInstanceFromFile e CoGetInstanceFromIStorage, fornecem a criação de instância em um sistema remoto e ativação de objeto. Há várias funções e métodos de interface cuja finalidade é criar objetos de um único tipo e fornecer um ponteiro para uma interface nesse objeto.

Sintaxe

HRESULT CoGetClassObject(
  [in]           REFCLSID rclsid,
  [in]           DWORD    dwClsContext,
  [in, optional] LPVOID   pvReserved,
  [in]           REFIID   riid,
  [out]          LPVOID   *ppv
);

Parâmetros

[in] rclsid

O CLSID associado aos dados e ao código que você usará para criar os objetos.

[in] dwClsContext

O contexto no qual o código executável deve ser executado. Para habilitar uma ativação remota, inclua CLSCTX_REMOTE_SERVER. Para obter mais informações sobre os valores de contexto e seu uso, consulte a enumeração CLSCTX .

[in, optional] pvReserved

Um ponteiro para o computador no qual instanciar o objeto de classe. Se esse parâmetro for NULL, o objeto de classe será instanciado no computador atual ou no computador especificado sob a chave RemoteServerName da classe, de acordo com a interpretação do parâmetro dwClsCtx . Consulte COSERVERINFO.

[in] riid

Referência ao identificador da interface , que será fornecido em ppv no retorno bem-sucedido. Essa interface será usada para se comunicar com o objeto de classe. Normalmente, esse valor é IID_IClassFactory, embora outros valores, como IID_IClassFactory2 que dá suporte a uma forma de licenciamento, sejam permitidos. Todos os IIDs de interface definidos por OLE são definidos nos arquivos de cabeçalho OLE como IID_interfacename, em que interfacename é o nome da interface.

[out] ppv

O 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.

Valor retornado

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

Código de retorno	Descrição
S_OK	A localização e a conexão com o objeto de classe especificado foram bem-sucedidas.
REGDB_E_CLASSNOTREG	O CLSID não está registrado corretamente. Esse erro também pode indicar que o valor especificado em dwClsContext não está no registro.
E_NOINTERFACE	O objeto apontado por ppv não dá suporte à interface identificada por riid ou à operação QueryInterface no objeto de classe retornado E_NOINTERFACE.
REGDB_E_READREGDB	Erro ao ler o banco de dados de registro.
CO_E_DLLNOTFOUND	A DLL em processo ou a DLL do manipulador não foram encontradas (dependendo do contexto).
CO_E_APPNOTFOUND	O executável (.exe) não foi encontrado (somente CLSCTX_LOCAL_SERVER).
E_ACCESSDENIED	Houve uma falha de acesso geral no carregamento.
CO_E_ERRORINDLL	Há um erro na imagem executável.
CO_E_APPDIDNTREG	O executável foi iniciado, mas não registrou o objeto de classe (e pode ter sido desligado).

Comentários

Um objeto de classe no OLE é um objeto intermediário que dá suporte a uma interface que permite operações comuns a um grupo de objetos. Os objetos nesse grupo são instâncias derivadas da mesma definição de objeto representada por um único CLSID. Normalmente, a interface implementada em um objeto de classe é IClassFactory, por meio da qual você pode criar instâncias de objeto de uma determinada definição (classe).

Uma chamada para CoGetClassObject cria, inicializa e fornece ao chamador acesso (por meio de um ponteiro para uma interface especificada com o parâmetro riid ) para o objeto de classe. O objeto de classe é aquele associado ao CLSID que você especifica no parâmetro rclsid . Os detalhes de como o sistema localiza o código e os dados associados em um computador são transparentes para o chamador, assim como o carregamento dinâmico de qualquer código que ainda não esteja carregado.

Se o contexto de classe for CLSCTX_REMOTE_SERVER, indicando que a ativação remota é necessária, a estrutura COSERVERINFO fornecida no parâmetro pServerInfo permite que você especifique o computador no qual o servidor está localizado. Para obter informações sobre o algoritmo usado para localizar um servidor remoto quando pServerInfo for NULL, consulte a enumeração CLSCTX .

Há dois locais para encontrar um CLSID para uma classe:

O registro contém uma associação entre CLSIDs e sufixos de arquivo e entre CLSIDs e assinaturas de arquivo para determinar a classe de um objeto.
Quando um objeto é salvo no armazenamento persistente, seu CLSID é armazenado com seus dados.

Para criar e inicializar objetos de documento OLE inseridos ou vinculados, não é necessário chamar CoGetClassObject diretamente. Em vez disso, chame a função OleCreate ou OleCreateXXX . Essas funções encapsulam todo o processo de instanciação e inicialização do objeto e chamam, entre outras funções, CoGetClassObject.

O parâmetro riid especifica a interface que o cliente usará para se comunicar com o objeto de classe. Na maioria dos casos, essa interface é IClassFactory. Isso fornece acesso ao método CreateInstance , por meio do qual o chamador pode criar um objeto não inicializado do tipo especificado em sua implementação. Todas as classes registradas no sistema com um CLSID devem implementar IClassFactory.

Em casos raros, no entanto, talvez você queira especificar alguma outra interface que defina operações comuns a um conjunto de objetos. Por exemplo, da maneira como o OLE implementa monikers, a interface no objeto de classe é IParseDisplayName, usada para transformar o nome de exibição de um objeto em um moniker.

O parâmetro dwClsContext especifica o contexto de execução, permitindo que um CLSID seja associado a diferentes partes de código em contextos de execução diferentes. A enumeração CLSCTX especifica os sinalizadores de contexto disponíveis. CoGetClassObject consulta (conforme apropriado para o contexto indicado) tanto o Registro quanto os objetos de classe que estão registrados no momento chamando a função CoRegisterClassObject .

Para liberar um objeto de classe, use o método Release do objeto de classe. A função CoRevokeClassObject deve ser usada apenas para remover o CLSID de um objeto de classe do registro do sistema.

Requisitos


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