Редагувати

Поділитися через

COM_INTERFACE_ENTRY Macros

  • Стаття

These macros enter an object's interfaces into its COM map so that they can be accessed by QueryInterface. The order of entries in the COM map is the order interfaces will be checked for a matching IID during QueryInterface.

Macro Description
COM_INTERFACE_ENTRY Enters interfaces into the COM interface map.
COM_INTERFACE_ENTRY2 Use this macro to disambiguate two branches of inheritance.
COM_INTERFACE_ENTRY_IID Use this macro to enter the interface into the COM map and specify its IID.
COM_INTERFACE_ENTRY2_IID Same as COM_INTERFACE_ENTRY2, except you can specify a different IID.
COM_INTERFACE_ENTRY_AGGREGATE When the interface identified by iid is queried for, COM_INTERFACE_ENTRY_AGGREGATE forwards to punk.
COM_INTERFACE_ENTRY_AGGREGATE_BLIND Same as COM_INTERFACE_ENTRY_AGGREGATE, except that querying for any IID results in forwarding the query to punk.
COM_INTERFACE_ENTRY_AUTOAGGREGATE Same as COM_INTERFACE_ENTRY_AGGREGATE, except if punk is NULL, it automatically creates the aggregate described by the clsid.
COM_INTERFACE_ENTRY_AUTOAGGREGATE_BLIND Same as COM_INTERFACE_ENTRY_AUTOAGGREGATE, except that querying for any IID results in forwarding the query to punk, and if punk is NULL, automatically creating the aggregate described by the clsid.
COM_INTERFACE_ENTRY_BREAK Causes your program to call DebugBreak when the specified interface is queried for.
COM_INTERFACE_ENTRY_CACHED_TEAR_OFF Saves the interface-specific data for every instance.
COM_INTERFACE_ENTRY_TEAR_OFF Exposes your tear-off interfaces.
COM_INTERFACE_ENTRY_CHAIN Processes the COM map of the base class when the processing reaches this entry in the COM map.
COM_INTERFACE_ENTRY_FUNC A general mechanism for hooking into ATL's QueryInterface logic.
COM_INTERFACE_ENTRY_FUNC_BLIND Same as COM_INTERFACE_ENTRY_FUNC, except that querying for any IID results in a call to func.
COM_INTERFACE_ENTRY_NOINTERFACE Returns E_NOINTERFACE and terminates COM map processing when the specified interface is queried for.

Requirements

Header: atlcom.h

COM_INTERFACE_ENTRY

Enters interfaces into the COM interface map.

Syntax

COM_INTERFACE_ENTRY( x )

Parameters

x
[in] The name of an interface your class object derives from directly.

Remarks

Typically, this is the entry type you use most often.

Example

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

Requirements

Header: atlcom.h

COM_INTERFACE_ENTRY2

Use this macro to disambiguate two branches of inheritance.

COM_INTERFACE_ENTRY2(x, x2)

Parameters

x
[in] The name of an interface you want to expose from your object.

x2
[in] The name of the inheritance branch from which x is exposed.

Remarks

For example, if you derive your class object from two dual interfaces, you expose IDispatch using COM_INTERFACE_ENTRY2 since IDispatch can be obtained from either one of the 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 this macro to enter the interface into the COM map and specify its IID.

COM_INTERFACE_ENTRY_IID(iid, x)

Parameters

iid
[in] The GUID of the interface exposed.

x
[in] The name of the class whose vtable will be exposed as the interface identified by 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

Same as COM_INTERFACE_ENTRY2, except you can specify a different IID.

COM_INTERFACE_ENTRY2_IID(iid, x, x2)

Parameters

iid
[in] The GUID you are specifying for the interface.

x
[in] The name of an interface that your class object derives from directly.

x2
[in] The name of a second interface that your class object derives from directly.

COM_INTERFACE_ENTRY_AGGREGATE

When the interface identified by iid is queried for, COM_INTERFACE_ENTRY_AGGREGATE forwards to punk.

COM_INTERFACE_ENTRY_AGGREGATE(iid, punk)

Parameters

iid
[in] The GUID of the interface queried for.

punk
[in] The name of an IUnknown pointer.

Remarks

The punk parameter is assumed to point to the inner unknown of an aggregate or to NULL, in which case the entry is ignored. Typically, you would CoCreate the aggregate in FinalConstruct.

Example

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

COM_INTERFACE_ENTRY_AGGREGATE_BLIND

Same as COM_INTERFACE_ENTRY_AGGREGATE, except that querying for any IID results in forwarding the query to punk.

COM_INTERFACE_ENTRY_AGGREGATE_BLIND(punk)

Parameters

punk
[in] The name of an IUnknown pointer.

Remarks

If the interface query fails, processing of the COM map continues.

Example

BEGIN_COM_MAP(COuter2)
   COM_INTERFACE_ENTRY_AGGREGATE_BLIND(m_punkAggBlind)
END_COM_MAP()

COM_INTERFACE_ENTRY_AUTOAGGREGATE

Same as COM_INTERFACE_ENTRY_AGGREGATE, except if punk is NULL, it automatically creates the aggregate described by the clsid.

COM_INTERFACE_ENTRY_AUTOAGGREGATE(iid, punk, clsid)

Parameters

iid
[in] The GUID of the interface queried for.

punk
[in] The name of an IUnknown pointer. Must be a member of the class containing the COM map.

clsid
[in] The identifier of the aggregate that will be created if punk is NULL.

Remarks

Example

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

COM_INTERFACE_ENTRY_AUTOAGGREGATE_BLIND

Same as COM_INTERFACE_ENTRY_AUTOAGGREGATE, except that querying for any IID results in forwarding the query to punk, and if punk is NULL, automatically creating the aggregate described by the clsid.

COM_INTERFACE_ENTRY_AUTOAGGREGATE_BLIND(punk, clsid)

Parameters

punk
[in] The name of an IUnknown pointer. Must be a member of the class containing the COM map.

clsid
[in] The identifier of the aggregate that will be created if punk is NULL.

Remarks

If the interface query fails, processing of the COM map continues.

Example

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

COM_INTERFACE_ENTRY_BREAK

Causes your program to call DebugBreak when the specified interface is queried for.

COM_INTERFACE_ENTRY_BREAK(x)

Parameters

x
[in] Text used to construct the interface identifier.

Remarks

The interface IID will be constructed by appending x to IID_. For example, if x is IPersistStorage, the IID will be IID_IPersistStorage.

COM_INTERFACE_ENTRY_CACHED_TEAR_OFF

Saves the interface-specific data for every instance.

COM_INTERFACE_ENTRY_CACHED_TEAR_OFF(iid, x, punk)

Parameters

iid
[in] The GUID of the tear-off interface.

x
[in] The name of the class implementing the interface.

punk
[in] The name of an IUnknown pointer. Must be a member of the class containing the COM map. Should be initialized to NULL in the class object's constructor.

Remarks

If the interface is not used, this lowers the overall instance size of your object.

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

Exposes your tear-off interfaces.

COM_INTERFACE_ENTRY_TEAR_OFF(iid, x)

Parameters

iid
[in] The GUID of the tear-off interface.

x
[in] The name of the class implementing the interface.

Remarks

A tear-off interface is implemented as a separate object that is instantiated every time the interface it represents is queried for. Typically, you build your interface as a tear-off if the interface is rarely used, since this saves a vtable pointer in every instance of your main object. The tear-off is deleted when its reference count becomes zero. The class implementing the tear-off should be derived from CComTearOffObjectBase and have its own COM map.

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

Processes the COM map of the base class when the processing reaches this entry in the COM map.

COM_INTERFACE_ENTRY_CHAIN(classname)

Parameters

classname
[in] A base class of the current object.

Remarks

For example, in the following code:

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

Note that the first entry in the COM map must be an interface on the object containing the COM map. Thus, you cannot start your COM map entries with COM_INTERFACE_ENTRY_CHAIN, which causes the COM map of a different object to be searched at the point where COM_INTERFACE_ENTRY_CHAIN(COtherObject) appears in your object's COM map. If you want to search the COM map of another object first, add an interface entry for IUnknown to your COM map, then chain the other object's COM map. For example:

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

COM_INTERFACE_ENTRY_FUNC

A general mechanism for hooking into ATL's QueryInterface logic.

COM_INTERFACE_ENTRY_FUNC(iid, dw, func)

Parameters

iid
[in] The GUID of the interface exposed.

dw
[in] A parameter passed through to the func.

func
[in] The function pointer that will return iid.

Remarks

If iid matches the IID of the interface queried for, then the function specified by func is called. The declaration for the function should be:

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

When your function is called, pv points to your class object. The riid parameter refers to the interface being queried for, ppv is the pointer to the location where the function should store the pointer to the interface, and dw is the parameter you specified in the entry. The function should set * ppv to NULL and return E_NOINTERFACE or S_FALSE if it chooses not to return an interface. With E_NOINTERFACE, COM map processing terminates. With S_FALSE, COM map processing continues, even though no interface pointer was returned. If the function returns an interface pointer, it should return S_OK.

COM_INTERFACE_ENTRY_FUNC_BLIND

Same as COM_INTERFACE_ENTRY_FUNC, except that querying for any IID results in a call to func.

COM_INTERFACE_ENTRY_FUNC_BLIND(dw, func)

Parameters

dw
[in] A parameter passed through to the func.

func
[in] The function that gets called when this entry in the COM map is processed.

Remarks

Any failure will cause processing to continue on the COM map. If the function returns an interface pointer, it should return S_OK.

COM_INTERFACE_ENTRY_NOINTERFACE

Returns E_NOINTERFACE and terminates COM map processing when the specified interface is queried for.

COM_INTERFACE_ENTRY_NOINTERFACE(x)

Parameters

x
[in] Text used to construct the interface identifier.

Remarks

You can use this macro to prevent an interface from being used in a particular case. For example, you can insert this macro into your COM map right before COM_INTERFACE_ENTRY_AGGREGATE_BLIND to prevent a query for the interface from being forwarded to the aggregate's inner unknown.

The interface IID will be constructed by appending x to IID_. For example, if x is IPersistStorage, the IID will be IID_IPersistStorage.