COM_INTERFACE_ENTRY Macros

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

Requerimentos

Cabeçalho: atlcom.h

COM_INTERFACE_ENTRY

Insere as interfaces no mapa de interface COM.

Sintaxe

COM_INTERFACE_ENTRY( x )

Parâmetros

x
[dentro] O nome de uma interface de onde deriva diretamente o teu objeto de classe.

Observações

Normalmente, este é o tipo de entrada que usa com mais frequência.

Example

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

Requerimentos

Cabeçalho: atlcom.h

COM_INTERFACE_ENTRY2

Use esta macro para desambiguar dois ramos da herança.

COM_INTERFACE_ENTRY2(x, x2)

Parâmetros

x
[dentro] O nome de uma interface que quer expor a partir do seu objeto.

x2
[dentro] O nome do ramo de herança do qual x está exposto.

Observações

Por exemplo, se derivar o seu objeto de classe a partir de duas interfaces duais, expõe IDispatch usando COM_INTERFACE_ENTRY2 pois IDispatch pode ser obtido a partir de qualquer uma das interfaces.

Example

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 esta macro para introduzir a interface no mapa COM e especificar o seu IID.

COM_INTERFACE_ENTRY_IID(iid, x)

Parâmetros

IID
[dentro] O GUID da interface exposto.

x
[dentro] O nome da classe cujo vtable será exposto como a interface identificada pelo iid.

Example

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

Igual ao COM_INTERFACE_ENTRY2, exceto que podes especificar um IID diferente.

COM_INTERFACE_ENTRY2_IID(iid, x, x2)

Parâmetros

IID
[dentro] O GUID que estás a especificar para a interface.

x
[dentro] O nome de uma interface de onde o teu objeto de classe deriva diretamente.

x2
[dentro] O nome de uma segunda interface da qual o teu objeto classe deriva diretamente.

COM_INTERFACE_ENTRY_AGGREGATE

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

COM_INTERFACE_ENTRY_AGGREGATE(iid, punk)

Parâmetros

IID
[dentro] O GUID da interface consultado para.

punk
[dentro] O nome de um IUnknown ponteiro.

Observações

Assume-se que o parâmetro punk aponta para o desconhecido interno de um agregado ou para NULL, caso em que a entrada é ignorada. Normalmente, o CoCreate agregado em FinalConstruct.

Example

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

COM_INTERFACE_ENTRY_AGGREGATE_BLIND

Igual a COM_INTERFACE_ENTRY_AGGREGATE, exceto que consultar qualquer IID faz com que a consulta seja encaminhada para o punk.

COM_INTERFACE_ENTRY_AGGREGATE_BLIND(punk)

Parâmetros

punk
[dentro] O nome de um IUnknown ponteiro.

Observações

Se a consulta da interface falhar, o processamento do mapa COM continua.

Example

BEGIN_COM_MAP(COuter2)
   COM_INTERFACE_ENTRY_AGGREGATE_BLIND(m_punkAggBlind)
END_COM_MAP()

COM_INTERFACE_ENTRY_AUTOAGGREGATE

Tal como COM_INTERFACE_ENTRY_AGGREGATE, exceto que se punk for NULL, cria automaticamente o agregado descrito pelo clsid.

COM_INTERFACE_ENTRY_AUTOAGGREGATE(iid, punk, clsid)

Parâmetros

IID
[dentro] O GUID da interface consultado para.

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

CLSID
[dentro] O identificador do agregado que será criado se o punk for NULL.

Observações

Example

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 consultar qualquer IID resulta em encaminhar a consulta para punk, e se punk for NULL, criar automaticamente o agregado descrito pelo clsid.

COM_INTERFACE_ENTRY_AUTOAGGREGATE_BLIND(punk, clsid)

Parâmetros

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

CLSID
[dentro] O identificador do agregado que será criado se o punk for NULL.

Observações

Se a consulta da interface falhar, o processamento do mapa COM continua.

Example

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

COM_INTERFACE_ENTRY_BREAK

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

COM_INTERFACE_ENTRY_BREAK(x)

Parâmetros

x
[dentro] Texto usado para construir o identificador da interface.

Observações

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

COM_INTERFACE_ENTRY_CACHED_TEAR_OFF

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

COM_INTERFACE_ENTRY_CACHED_TEAR_OFF(iid, x, punk)

Parâmetros

IID
[dentro] O GUID da interface de remoção.

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

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

Observações

Se a interface não for utilizada, isto reduz o tamanho total da instância do seu objeto.

Example

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 as tuas interfaces remotrices.

COM_INTERFACE_ENTRY_TEAR_OFF(iid, x)

Parâmetros

IID
[dentro] O GUID da interface de remoção.

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

Observações

Uma interface de remoção é implementada como um objeto separado que é instanciado sempre que a interface que representa é consultada. Normalmente, constróis a interface como um tear-off se a interface for raramente usada, pois isto poupa um ponteiro vtable em cada instância do teu objeto principal. A desmontagem é eliminada quando a sua contagem de referências se torna zero. A classe que implementa o tear-off deve ser derivada e CComTearOffObjectBase ter o seu próprio mapa COM.

Example

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 chega a esta entrada no mapa COM.

COM_INTERFACE_ENTRY_CHAIN(classname)

Parâmetros

nome de classe
[dentro] Uma classe base do objeto atual.

Observações

Por exemplo, no código a seguir:

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

Note que a primeira entrada no mapa COM deve ser uma interface no objeto que contém o mapa COM. Assim, não pode iniciar as entradas do mapa COM com COM_INTERFACE_ENTRY_CHAIN, o que faz com que o mapa COM de um objeto diferente seja pesquisado no ponto onde COM_INTERFACE_ENTRY_CHAIN(COtherObject) aparece no mapa COM do seu objeto. Se quiseres pesquisar primeiro o mapa COM de outro objeto, adiciona uma entrada de interface para IUnknown ao teu mapa COM, depois encadeia 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 se ligar à lógica de QueryInterface ATL.

COM_INTERFACE_ENTRY_FUNC(iid, dw, func)

Parâmetros

IID
[dentro] O GUID da interface exposto.

dw
[dentro] Um parâmetro passado para a func.

func
[dentro] O ponteiro de função que devolverá o iid.

Observações

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

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

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

COM_INTERFACE_ENTRY_FUNC_BLIND

Tal como COM_INTERFACE_ENTRY_FUNC, exceto que consultar qualquer IID resulta numa chamada para func.

COM_INTERFACE_ENTRY_FUNC_BLIND(dw, func)

Parâmetros

dw
[dentro] Um parâmetro passado para a func.

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

Observações

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

COM_INTERFACE_ENTRY_NOINTERFACE

Devolve E_NOINTERFACE e termina o processamento de mapas COM quando a interface especificada é consultada.

COM_INTERFACE_ENTRY_NOINTERFACE(x)

Parâmetros

x
[dentro] Texto usado para construir o identificador da interface.

Observações

Pode usar esta macro para impedir que uma interface seja usada num caso específico. Por exemplo, pode inserir esta macro no seu mapa COM mesmo antes de COM_INTERFACE_ENTRY_AGGREGATE_BLIND para evitar que uma consulta para a interface seja encaminhada para o desconhecido interno do agregado.

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