| description | title | ms.date | f1_keywords | helpviewer_keywords | ms.assetid | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Learn more about: COM_INTERFACE_ENTRY Macros |
COM Interface Entry Macros |
03/28/2017 |
|
|
19dcb768-2e1f-4b8d-a618-453a01a4bd00 |
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. |
Header: atlcom.h
Enters interfaces into the COM interface map.
COM_INTERFACE_ENTRY( x )
x
[in] The name of an interface your class object derives from directly.
Typically, this is the entry type you use most often.
BEGIN_COM_MAP(CThisExample)
COM_INTERFACE_ENTRY(IThisExample)
COM_INTERFACE_ENTRY(IDispatch)
COM_INTERFACE_ENTRY(ISupportErrorInfo)
END_COM_MAP()Header: atlcom.h
Use this macro to disambiguate two branches of inheritance.
COM_INTERFACE_ENTRY2(x, x2)
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.
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.
[!code-cppNVC_ATL_Windowing#118]
Use this macro to enter the interface into the COM map and specify its IID.
COM_INTERFACE_ENTRY_IID(iid, x)
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.
[!code-cppNVC_ATL_Windowing#117]
Same as COM_INTERFACE_ENTRY2, except you can specify a different IID.
COM_INTERFACE_ENTRY2_IID(iid, x, x2)
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.
When the interface identified by iid is queried for, COM_INTERFACE_ENTRY_AGGREGATE forwards to punk.
COM_INTERFACE_ENTRY_AGGREGATE(iid, punk)
iid
[in] The GUID of the interface queried for.
punk
[in] The name of an IUnknown pointer.
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.
[!code-cppNVC_ATL_Windowing#112]
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)
punk
[in] The name of an IUnknown pointer.
If the interface query fails, processing of the COM map continues.
[!code-cppNVC_ATL_Windowing#113]
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)
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.
[!code-cppNVC_ATL_Windowing#114]
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)
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.
If the interface query fails, processing of the COM map continues.
[!code-cppNVC_ATL_Windowing#115]
Causes your program to call DebugBreak when the specified interface is queried for.
COM_INTERFACE_ENTRY_BREAK(x)
x
[in] Text used to construct the interface identifier.
The interface IID will be constructed by appending x to IID_. For example, if x is IPersistStorage, the IID will be IID_IPersistStorage.
Saves the interface-specific data for every instance.
COM_INTERFACE_ENTRY_CACHED_TEAR_OFF(iid, x, punk)
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.
If the interface is not used, this lowers the overall instance size of your object.
[!code-cppNVC_ATL_COM#54]
Exposes your tear-off interfaces.
COM_INTERFACE_ENTRY_TEAR_OFF(iid, x)
iid
[in] The GUID of the tear-off interface.
x
[in] The name of the class implementing the interface.
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.
[!code-cppNVC_ATL_COM#1]
Processes the COM map of the base class when the processing reaches this entry in the COM map.
COM_INTERFACE_ENTRY_CHAIN(classname)
classname
[in] A base class of the current object.
For example, in the following code:
[!code-cppNVC_ATL_Windowing#116]
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:
[!code-cppNVC_ATL_Windowing#111]
A general mechanism for hooking into ATL's QueryInterface logic.
COM_INTERFACE_ENTRY_FUNC(iid, dw, func)
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.
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.
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)
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.
Any failure will cause processing to continue on the COM map. If the function returns an interface pointer, it should return S_OK.
Returns E_NOINTERFACE and terminates COM map processing when the specified interface is queried for.
COM_INTERFACE_ENTRY_NOINTERFACE(x)
x
[in] Text used to construct the interface identifier.
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.