Compartilhar via

Macros COM_INTERFACE_ENTRY

  • Artigo

Essas macros inserem as interfaces de um objeto em seu mapa COM para que possam ser acessadas por QueryInterface. A ordem das entradas no mapa COM é a ordem em que as interfaces de pedido serão verificadas para um IID correspondente durante QueryInterface.

Macro Descrição
COM_INTERFACE_ENTRY Insere interfaces no mapa da interface COM.
COM_INTERFACE_ENTRY2 Use essa macro para desambiguar dois branches de herança.
COM_INTERFACE_ENTRY_IID Use essa macro para inserir a interface no mapa COM e especificar seu IID.
COM_INTERFACE_ENTRY2_IID O mesmo que COM_INTERFACE_ENTRY2, exceto que você pode especificar um IID diferente.
COM_INTERFACE_ENTRY_AGGREGATE Quando a interface identificada por iid é consultada, COM_INTERFACE_ENTRY_AGGREGATE encaminha para punk.
COM_INTERFACE_ENTRY_AGGREGATE_BLIND O mesmo que COM_INTERFACE_ENTRY_AGGREGATE, exceto que a consulta por IID resulta no encaminhamento da consulta para punk.
COM_INTERFACE_ENTRY_AUTOAGGREGATE O mesmo que COM_INTERFACE_ENTRY_AGGREGATE, exceto se punk for NULL, pois ele criará automaticamente a agregação descrita pelo clsid.
COM_INTERFACE_ENTRY_AUTOAGGREGATE_BLIND O mesmo que COM_INTERFACE_ENTRY_AUTOAGGREGATE, exceto que a consulta por IID resulta no encaminhamento da consulta para punk e, se punk for NULL, criará automaticamente a agregação descrita pelo clsid.
COM_INTERFACE_ENTRY_BREAK Faz com que o programa chame DebugBreak quando a interface especificada é consultada.
COM_INTERFACE_ENTRY_CACHED_TEAR_OFF Salva os dados específicos da interface para cada instância.
COM_INTERFACE_ENTRY_TEAR_OFF Expõe suas interfaces destacáveis.
COM_INTERFACE_ENTRY_CHAIN Processa o mapa COM da classe base quando o processamento atinge essa entrada no mapa COM.
COM_INTERFACE_ENTRY_FUNC Um mecanismo geral para conectar-se à lógica QueryInterface da ATL.
COM_INTERFACE_ENTRY_FUNC_BLIND O mesmo que COM_INTERFACE_ENTRY_FUNC, exceto que a consulta por IID resulta em uma chamada a func.
COM_INTERFACE_ENTRY_NOINTERFACE Retorna E_NOINTERFACE e encerra o processamento de mapa COM quando a interface especificada é consultada.

Requisitos

Cabeçalho: atlcom.h

COM_INTERFACE_ENTRY

Insere interfaces no mapa da interface COM.

Sintaxe

COM_INTERFACE_ENTRY( x )

Parâmetros

x
[in] O nome de uma interface da qual seu objeto de classe deriva diretamente.

Comentários

Normalmente, esse é o tipo de entrada usado com mais frequência.

Exemplo

BEGIN_COM_MAP(CThisExample)
   COM_INTERFACE_ENTRY(IThisExample)
   COM_INTERFACE_ENTRY(IDispatch)
   COM_INTERFACE_ENTRY(ISupportErrorInfo)
END_COM_MAP()

Requisitos

Cabeçalho: atlcom.h

COM_INTERFACE_ENTRY2

Use essa macro para desambiguar dois branches de herança.

COM_INTERFACE_ENTRY2(x, x2)

Parâmetros

x
[in] O nome de uma interface que você deseja expor usando o objeto.

x2
[in] O nome do branch de herança do qual x é exposto.

Comentários

Por exemplo, se você derivar seu objeto de classe de duas interfaces duplas, exporá IDispatch usando COM_INTERFACE_ENTRY2 já que IDispatch pode ser obtido de uma das interfaces.

Exemplo

class ATL_NO_VTABLE CEntry2Example :
   public CEntry2ExampleBase, // CEntry2ExampleBase derives from IDispatch
   public IDispatchImpl<IEntry2Example, &IID_IEntry2Example, &LIBID_NVC_ATL_WindowingLib, /*wMajor =*/ 1, /*wMinor =*/ 0>,
   public CComCoClass<CEntry2Example, &CLSID_Entry2Example>
{
public:
   CEntry2Example()
   {
   }

BEGIN_COM_MAP(CEntry2Example)
   COM_INTERFACE_ENTRY(IEntry2Example)
   COM_INTERFACE_ENTRY2(IDispatch, IEntry2Example)
END_COM_MAP()
};

COM_INTERFACE_ENTRY_IID

Use essa macro para inserir a interface no mapa COM e especificar seu IID.

COM_INTERFACE_ENTRY_IID(iid, x)

Parâmetros

iid
[in] O GUID da interface exposta.

x
[in] O nome da classe cuja vtable será exposta como a interface identificada por iid.

Exemplo

BEGIN_COM_MAP(CExample)
   COM_INTERFACE_ENTRY(IExample)
   COM_INTERFACE_ENTRY_IID(IID_IDispatch, CExampleDispatch)
   COM_INTERFACE_ENTRY(IExampleBase)
   COM_INTERFACE_ENTRY(ISupportErrorInfo)
END_COM_MAP()

COM_INTERFACE_ENTRY2_IID

O mesmo que COM_INTERFACE_ENTRY2, exceto que você pode especificar um IID diferente.

COM_INTERFACE_ENTRY2_IID(iid, x, x2)

Parâmetros

iid
[in] O GUID que você está especificando para a interface.

x
[in] O nome de uma interface da qual seu objeto de classe deriva diretamente.

x2
[in] O nome de uma segunda interface da qual seu objeto de classe deriva diretamente.

COM_INTERFACE_ENTRY_AGGREGATE

Quando a interface identificada por iid é consultada, COM_INTERFACE_ENTRY_AGGREGATE encaminha para punk.

COM_INTERFACE_ENTRY_AGGREGATE(iid, punk)

Parâmetros

iid
[in] O GUID da interface consultada.

punk
[in] O nome de um ponteiro IUnknown.

Comentários

O parâmetro punk é assumido para apontar para o desconhecido interno de uma agregação ou para NULL. Nesse caso, a entrada é ignorada. Normalmente, você faria CoCreate a agregação em FinalConstruct.

Exemplo

BEGIN_COM_MAP(COuter1)
   COM_INTERFACE_ENTRY_AGGREGATE(__uuidof(IAgg), m_punkAgg)
END_COM_MAP()

COM_INTERFACE_ENTRY_AGGREGATE_BLIND

O mesmo que COM_INTERFACE_ENTRY_AGGREGATE, exceto que a consulta por IID resulta no encaminhamento da consulta para punk.

COM_INTERFACE_ENTRY_AGGREGATE_BLIND(punk)

Parâmetros

punk
[in] O nome de um ponteiro IUnknown.

Comentários

Se a consulta de interface falhar, o processamento do mapa COM continuará.

Exemplo

BEGIN_COM_MAP(COuter2)
   COM_INTERFACE_ENTRY_AGGREGATE_BLIND(m_punkAggBlind)
END_COM_MAP()

COM_INTERFACE_ENTRY_AUTOAGGREGATE

O mesmo que COM_INTERFACE_ENTRY_AGGREGATE, exceto se punk for NULL, pois ele criará automaticamente a agregação descrita pelo clsid.

COM_INTERFACE_ENTRY_AUTOAGGREGATE(iid, punk, clsid)

Parâmetros

iid
[in] O GUID da interface consultada.

punk
[in] O nome de um ponteiro IUnknown. Deve ser um membro da classe que contém o mapa COM.

clsid
[in] O identificador da agregação que será criado se punk for NULL.

Comentários

Exemplo

BEGIN_COM_MAP(COuter3)
   COM_INTERFACE_ENTRY_AUTOAGGREGATE(__uuidof(IAutoAgg), m_punkAutoAgg, CLSID_CAutoAgg)
END_COM_MAP()

COM_INTERFACE_ENTRY_AUTOAGGREGATE_BLIND

O mesmo que COM_INTERFACE_ENTRY_AUTOAGGREGATE, exceto que a consulta por IID resulta no encaminhamento da consulta para punk e, se punk for NULL, criará automaticamente a agregação descrita pelo clsid.

COM_INTERFACE_ENTRY_AUTOAGGREGATE_BLIND(punk, clsid)

Parâmetros

punk
[in] O nome de um ponteiro IUnknown. Deve ser um membro da classe que contém o mapa COM.

clsid
[in] O identificador da agregação que será criado se punk for NULL.

Comentários

Se a consulta de interface falhar, o processamento do mapa COM continuará.

Exemplo

BEGIN_COM_MAP(COuter4)
   COM_INTERFACE_ENTRY_AUTOAGGREGATE_BLIND(m_punkAutoAggB, CLSID_CAutoAggB)
END_COM_MAP()

COM_INTERFACE_ENTRY_BREAK

Faz com que o programa chame DebugBreak quando a interface especificada é consultada.

COM_INTERFACE_ENTRY_BREAK(x)

Parâmetros

x
[in] Texto usado para construir o identificador de interface.

Comentários

O IID da interface será construído acrescentando x a IID_. Por exemplo, se x for IPersistStorage, o IID será IID_IPersistStorage.

COM_INTERFACE_ENTRY_CACHED_TEAR_OFF

Salva os dados específicos da interface para cada instância.

COM_INTERFACE_ENTRY_CACHED_TEAR_OFF(iid, x, punk)

Parâmetros

iid
[in] O GUID da interface destacável.

x
[in] O nome da classe que implementa a interface.

punk
[in] O nome de um ponteiro IUnknown. Deve ser um membro da classe que contém o mapa COM. Deve ser inicializado como NULL no construtor do objeto de classe.

Comentários

Se a interface não for usada, isso reduzirá o tamanho geral da instância do objeto.

Exemplo

BEGIN_COM_MAP(COuter)
   COM_INTERFACE_ENTRY(IOuter)
   COM_INTERFACE_ENTRY_CACHED_TEAR_OFF(IID_ITearOff, CTearOff, punkTearOff)
END_COM_MAP()

COM_INTERFACE_ENTRY_TEAR_OFF

Expõe suas interfaces destacáveis.

COM_INTERFACE_ENTRY_TEAR_OFF(iid, x)

Parâmetros

iid
[in] O GUID da interface destacável.

x
[in] O nome da classe que implementa a interface.

Comentários

Uma interface destacável é implementada como um objeto separado que é instanciado toda vez que a interface que ela representa é consultada. Normalmente, você cria sua interface como destacável se a interface raramente é usada, pois isso salva um ponteiro vtable em cada instância do objeto principal. O elemento destacável é excluído quando sua contagem de referência se torna zero. A classe que implementa o elemento destacável deve ser derivada de CComTearOffObjectBase e ter seu próprio mapa COM.

Exemplo

BEGIN_COM_MAP(CBeeper)
   COM_INTERFACE_ENTRY(IBeeper)
   COM_INTERFACE_ENTRY(IDispatch)
   COM_INTERFACE_ENTRY_TEAR_OFF(IID_ISupportErrorInfo, CBeeper2)
END_COM_MAP()

COM_INTERFACE_ENTRY_CHAIN

Processa o mapa COM da classe base quando o processamento atinge essa entrada no mapa COM.

COM_INTERFACE_ENTRY_CHAIN(classname)

Parâmetros

classname
[in] Uma classe base do objeto atual.

Comentários

Por exemplo, no seguinte código:

BEGIN_COM_MAP(COuterObject)
   COM_INTERFACE_ENTRY2(IDispatch, IOuterObject)
   COM_INTERFACE_ENTRY_CHAIN(CBase)
END_COM_MAP()

Observe que a primeira entrada no mapa COM deve ser uma interface no objeto que contém o mapa COM. Portanto, você não pode iniciar as entradas de mapa COM com COM_INTERFACE_ENTRY_CHAIN, o que faz com que o mapa COM de um objeto diferente seja pesquisado no ponto em que COM_INTERFACE_ENTRY_CHAIN(COtherObject) aparece no mapa COM do objeto. Se você quiser pesquisar o mapa COM de outro objeto primeiro, adicione uma entrada de interface para IUnknown para o mapa COM e encadeie o mapa COM do outro objeto. Por exemplo:

BEGIN_COM_MAP(CThisObject)
   COM_INTERFACE_ENTRY(IUnknown)
   COM_INTERFACE_ENTRY_CHAIN(CBase)
END_COM_MAP()

COM_INTERFACE_ENTRY_FUNC

Um mecanismo geral para conectar-se à lógica QueryInterface da ATL.

COM_INTERFACE_ENTRY_FUNC(iid, dw, func)

Parâmetros

iid
[in] O GUID da interface exposta.

dw
[in] Um parâmetro passado para func.

func
[in] O ponteiro de função que retornará iid.

Comentários

Se iid corresponder ao IID da interface consultada, a função especificada por func será chamada. A declaração para a função deve ser:

HRESULT WINAPI func(void* pv, REFIID riid, LPVOID* ppv, DWORD_PTR dw);

Quando sua função é chamada, pv aponta para o objeto de classe. O parâmetro riid refere-se à interface que está sendo consultada, ppv é o ponteiro para o local em que a função deve armazenar o ponteiro para a interface e dw é o parâmetro especificado na entrada. A função deverá definir * ppv como NULL e retornar E_NOINTERFACE ou S_FALSE se optar por não retornar uma interface. Com E_NOINTERFACE, o processamento de mapa COM termina. Com S_FALSE, o processamento de mapa COM continua, mesmo que nenhum ponteiro de interface tenha sido retornado. Se a função retornar um ponteiro de interface, ela deverá retornar S_OK.

COM_INTERFACE_ENTRY_FUNC_BLIND

O mesmo que COM_INTERFACE_ENTRY_FUNC, exceto que a consulta por IID resulta em uma chamada a func.

COM_INTERFACE_ENTRY_FUNC_BLIND(dw, func)

Parâmetros

dw
[in] Um parâmetro passado para func.

func
[in] A função que é chamada quando essa entrada no mapa COM é processada.

Comentários

Qualquer falha fará com que o processamento continue no mapa COM. Se a função retornar um ponteiro de interface, ela deverá retornar S_OK.

COM_INTERFACE_ENTRY_NOINTERFACE

Retorna E_NOINTERFACE e encerra o processamento de mapa COM quando a interface especificada é consultada.

COM_INTERFACE_ENTRY_NOINTERFACE(x)

Parâmetros

x
[in] Texto usado para construir o identificador de interface.

Comentários

Você pode usar essa macro para impedir que uma interface seja usada em um caso específico. Por exemplo, você pode inserir essa macro no mapa COM antes de COM_INTERFACE_ENTRY_AGGREGATE_BLIND para impedir que uma consulta para a interface seja encaminhada para o desconhecido interno da agregação.

O IID da interface será construído acrescentando x a IID_. Por exemplo, se x for IPersistStorage, o IID será IID_IPersistStorage.