Macros COM_INTERFACE_ENTRY
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.
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de