Classe CComCoClass

Artigo
04/03/2023

Essa classe fornece métodos para criar instâncias de uma classe e obter suas propriedades.

Sintaxe

template <class T, const CLSID* pclsid = &CLSID_NULL>
class CComCoClass

Parâmetros

T
Sua classe, derivada de CComCoClass.

pclsid
Um ponteiro para o CLSID do objeto.

Membros

Métodos públicos

Nome	Descrição
CComCoClass::CreateInstance	(Estático) Cria uma instância da classe e consultas para uma interface.
CComCoClass::Error	(Estático) Retorna informações de erro avançadas para o cliente.
CComCoClass::GetObjectCLSID	(Estático) Retorna o identificador de classe do objeto.
CComCoClass::GetObjectDescription	(Estático) Substitua para retornar a descrição do objeto.

Comentários

CComCoClass fornece métodos para recuperar o CLSID de um objeto, definir informações de erro e criar instâncias da classe. Qualquer classe registrada no mapa de objetos deve ser derivada de CComCoClass.

CComCoClass também define a fábrica de classes padrão e o modelo de agregação para seu objeto. CComCoClass usa as duas macros abaixo:

DECLARE_CLASSFACTORY Declara a fábrica de classes como CComClassFactory.
DECLARE_AGGREGATABLE Declara que seu objeto pode ser agregado.

Você pode substituir qualquer um desses padrões especificando outra macro em sua definição de classe. Por exemplo, para usar CComClassFactory2 em vez de CComClassFactory, especifique a macro DECLARE_CLASSFACTORY2:

class ATL_NO_VTABLE CMyClass2 :
   public CComObjectRootEx<CComSingleThreadModel>,
   public CComCoClass<CMyClass2, &CLSID_MyClass>,
   public IDispatchImpl<IMyClass, &IID_IMyClass, &LIBID_NVC_ATL_COMLib, /*wMajor =*/ 1, /*wMinor =*/ 0>,
   public IDispatchImpl<IMyDualInterface, &__uuidof(IMyDualInterface), &LIBID_NVC_ATL_COMLib, /* wMajor = */ 1, /* wMinor = */ 0>
{
public:
   DECLARE_CLASSFACTORY2(CMyLicense)

   // Remainder of class declaration omitted

Requisitos

Cabeçalho: atlcom.h

CComCoClass::CreateInstance

Use essas funções CreateInstance para criar uma instância de um objeto COM e recuperar um ponteiro de interface sem usar a API COM.

template <class  Q>
static HRESULT CreateInstance( Q** pp);

template <class  Q>
static HRESULT CreateInstance(IUnknown* punkOuter, Q** pp);

Parâmetros

Q
A interface COM que deve ser retornada via pp.

punkOuter
[in] O desconhecido externo ou o desconhecido de controle da agregação.

pp
[out] O endereço de uma variável de ponteiro que recebe o ponteiro de interface solicitado se a criação é bem-sucedida.

Valor de retorno

Um valor HRESULT padrão. Confira CoCreateInstance no SDK do Windows para obter uma descrição de possíveis valores retornados.

Comentários

Use a primeira sobrecarga dessa função para a criação típica de objeto. Use a segunda sobrecarga quando precisar agregar o objeto que está sendo criado.

A classe da ATL que implementa o objeto COM necessário (ou seja, a classe usada como o primeiro parâmetro de modelo para CComCoClass) deve estar no mesmo projeto que o código de chamada. A criação do objeto COM é realizada pela fábrica de classes registrada para essa classe da ATL.

Essas funções são úteis para criar objetos que você impediu de serem criáveis externamente usando a macro OBJECT_ENTRY_NON_CREATEABLE_EX_AUTO. Elas também são úteis em situações em que você deseja evitar a API COM por motivos de eficiência.

Observe que o Q da interface deve ter um IID associado a ela que possa ser recuperado usando o operador __uuidof.

Exemplo

No exemplo a seguir, CDocument é uma classe da ATL gerada pelo assistente derivada de CComCoClass que implementa a interface IDocument. A classe é registrada no mapa de objetos com a macro OBJECT_ENTRY_NON_CREATEABLE_EX_AUTO para que os clientes não possam criar instâncias do documento usando CoCreateInstance. CApplication é um CoClass que fornece um método em uma de suas próprias interfaces COM para criar instâncias da classe de documento. O código abaixo mostra como é fácil criar instâncias da classe de documento usando o membro CreateInstance herdado da classe base CComCoClass.

STDMETHODIMP CMyApp::CreateDocument( /* [out, retval] */ IDocument** ppDoc)
{
   *ppDoc = NULL;
   return CMyDoc::CreateInstance(ppDoc);
}

CComCoClass::Error

Essa função estática configura a interface IErrorInfo para fornecer informações de erro ao cliente.

static HRESULT WINAPI Error(
    LPCOLESTR lpszDesc,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0);

static HRESULT WINAPI Error(
    LPCOLESTR lpszDesc,
    DWORD dwHelpID,
    LPCOLESTR lpszHelpFile,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0);

static HRESULT WINAPI Error(
    LPCSTR lpszDesc,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0);

static HRESULT WINAPI Error(
    LPCSTR lpszDesc,
    DWORD dwHelpID,
    LPCSTR lpszHelpFile,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0);

static HRESULT WINAPI Error(
    UINT nID,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0,
    HINSTANCE hInst = _AtlBaseModule.GetResourceInstance ());

static HRESULT Error(
    UINT nID,
    DWORD dwHelpID,
    LPCOLESTR lpszHelpFile,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0,
    HINSTANCE hInst = _AtlBaseModule.GetResourceInstance());

Parâmetros

lpszDesc
[in] A cadeia de caracteres que descreve o erro. A versão Unicode de Error especifica que lpszDesc é do tipo LPCOLESTR. A versão ANSI especifica um tipo de LPCSTR.

iid
[in] O IID da interface que definirá o erro ou GUID_NULL (o valor padrão) se o erro for definido pelo sistema operacional.

hRes
[in] O HRESULT que você deseja retornar ao chamador. O valor padrão é 0. Para obter mais detalhes sobre hRes, confira Comentários.

Nid
[in] O identificador de recurso em que a cadeia de caracteres de descrição do erro é armazenada. Esse valor deve estar entre 0x0200 e 0xFFFF, inclusive. Em builds de depuração, um ASSERT resultará se nID não indexar uma cadeia de caracteres válida. Nos builds de versão, a cadeia de caracteres de descrição do erro será definida como "Erro Desconhecido".

dwHelpID
[in] O identificador de contexto de ajuda para o erro.

lpszHelpFile
[in] O caminho e o nome do arquivo de ajuda que descreve o erro.

hInst
[in] O identificador para o recurso. Por padrão, esse parâmetro é _AtlModule::GetResourceInstance, em que _AtlModule é a instância global do CAtlModule.

Valor de retorno

Um valor HRESULT padrão. Para obter detalhes, consulte Observações.

Comentários

Para chamar Error, seu objeto deve implementar a interface ISupportErrorInfo.

Se o parâmetro hRes for diferente de zero, Error retornará o valor de hRes. Se hRes for zero, as quatro primeiras versões de Error retornarão DISP_E_EXCEPTION. As duas últimas versões retornam o resultado da macro MAKE_HRESULT( 1, FACILITY_ITF, nID ).

CComCoClass::GetObjectCLSID

Fornece um modo consistente de recuperar o CLSID do objeto.

static const CLSID& WINAPI GetObjectCLSID();

Valor de retorno

O identificador de classe do objeto.

CComCoClass::GetObjectDescription

Essa função estática recupera a descrição do texto do objeto de classe.

static LPCTSTR WINAPI GetObjectDescription();

Valor de retorno

A descrição do objeto de classe.

Comentários

A implementação padrão retorna NULL. Você pode substituir esse método pela macro DECLARE_OBJECT_DESCRIPTION. Por exemplo:

class ATL_NO_VTABLE CMyDoc :
   public CComObjectRootEx<CComSingleThreadModel>,
   public CComCoClass<CMyDoc, &CLSID_MyDoc>,
   public IDocument
{
public:
   DECLARE_OBJECT_DESCRIPTION("My Document Object 1.0")

   // Remainder of class declaration omitted.

GetObjectDescription é chamado por IComponentRegistrar::GetComponents. IComponentRegistrar é uma interface do Automação que permite registrar e cancelar o registro de componentes individuais em uma DLL. Ao criar um objeto do Registrador de Componentes com o Assistente de Projeto da ATL, o assistente implementará automaticamente a interface IComponentRegistrar. IComponentRegistrar normalmente é usado pelo Microsoft Transaction Server.

Para obter mais informações sobre o Assistente de Projeto da ATL, confira o artigo Criar um projeto da ATL.

Confira também

Visão geral da aula

Compartilhar via

Classe CComCoClass

Sintaxe

Parâmetros

Membros

Métodos públicos

Comentários

Requisitos

CComCoClass::CreateInstance

Parâmetros

Valor de retorno

Comentários

Exemplo

CComCoClass::Error

Parâmetros

Valor de retorno

Comentários

CComCoClass::GetObjectCLSID

Valor de retorno

CComCoClass::GetObjectDescription

Valor de retorno

Comentários

Confira também

Comentários

Recursos adicionais