---
title: "COM Interface Entry Macros"
ms.date: "03/28/2017"
f1_keywords: ["atlcom/ATL::COM_INTERFACE_ENTRY", "atlcom/ATL::COM_INTERFACE_ENTRY_IID", "atlcom/ATL::COM_INTERFACE_ENTRY_AGGREGATE", "atlcom/ATL::COM_INTERFACE_ENTRY_AGGREGATE_BLIND", "atlcom/ATL::COM_INTERFACE_ENTRY_AUTOAGGREGATE", "atlcom/ATL::COM_INTERFACE_ENTRY_AUTOAGGREGATE_BLIND", "atlcom/ATL::COM_INTERFACE_ENTRY_BREAK", "atlcom/ATL::COM_INTERFACE_ENTRY_CACHED_TEAR_OFF", "atlcom/ATL::COM_INTERFACE_ENTRY_TEAR_OFF", "atlcom/ATL::COM_INTERFACE_ENTRY_CHAIN", "atlcom/ATL::COM_INTERFACE_ENTRY_FUNC", "atlcom/ATL::COM_INTERFACE_ENTRY_FUNC_BLIND", "atlcom/ATL::COM_INTERFACE_ENTRY_NOINTERFACE"]
helpviewer_keywords: ["COM interfaces, COM interface entry macros"]
ms.assetid: 19dcb768-2e1f-4b8d-a618-453a01a4bd00
---
# 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](#com_interface_entry)|Enters interfaces into the COM interface map.|
|[COM_INTERFACE_ENTRY2](#com_interface_entry2)|Use this macro to disambiguate two branches of inheritance.|
|[COM_INTERFACE_ENTRY_IID](#com_interface_entry_iid)|Use this macro to enter the interface into the COM map and specify its IID.|
|[COM_INTERFACE_ENTRY2_IID](#com_interface_entry2_iid)|Same as [COM_INTERFACE_ENTRY2](#com_interface_entry2), except you can specify a different IID.|
|[COM_INTERFACE_ENTRY_AGGREGATE](#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](#com_interface_entry_aggregate_blind)|Same as [COM_INTERFACE_ENTRY_AGGREGATE](#com_interface_entry_aggregate), except that querying for any IID results in forwarding the query to *punk*.|
|[COM_INTERFACE_ENTRY_AUTOAGGREGATE](#com_interface_entry_autoaggregate)|Same as [COM_INTERFACE_ENTRY_AGGREGATE](#com_interface_entry_aggregate), except if *punk* is NULL, it automatically creates the aggregate described by the *clsid*.|
|[COM_INTERFACE_ENTRY_AUTOAGGREGATE_BLIND](#com_interface_entry_autoaggregate_blind)|Same as [COM_INTERFACE_ENTRY_AUTOAGGREGATE](#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](#com_interface_entry_break)|Causes your program to call [DebugBreak](/windows/win32/api/debugapi/nf-debugapi-debugbreak) when the specified interface is queried for.|
|[COM_INTERFACE_ENTRY_CACHED_TEAR_OFF](#com_interface_entry_cached_tear_off)|Saves the interface-specific data for every instance.|
|[COM_INTERFACE_ENTRY_TEAR_OFF](#com_interface_entry_tear_off)|Exposes your tear-off interfaces.|
|[COM_INTERFACE_ENTRY_CHAIN](#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](#com_interface_entry_func)|A general mechanism for hooking into ATL's `QueryInterface` logic.|
|[COM_INTERFACE_ENTRY_FUNC_BLIND](#com_interface_entry_func_blind)|Same as [COM_INTERFACE_ENTRY_FUNC](#com_interface_entry_func), except that querying for any IID results in a call to *func*.|
|[COM_INTERFACE_ENTRY_NOINTERFACE](#com_interface_entry_nointerface)|Returns E_NOINTERFACE and terminates COM map processing when the specified interface is queried for.|

## Requirements

**Header:** atlcom.h

## <a name="com_interface_entry"></a> COM_INTERFACE_ENTRY

Enters interfaces into the COM interface map.

### Syntax

```
COM_INTERFACE_ENTRY( x )
```

### Parameters

*x*<br/>
[in] The name of an interface your class object derives from directly.

### Remarks

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

### Example

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

### Requirements

**Header:** atlcom.h

## <a name="com_interface_entry2"></a> COM_INTERFACE_ENTRY2

Use this macro to disambiguate two branches of inheritance.

```
COM_INTERFACE_ENTRY2(x, x2)
```

### Parameters

*x*<br/>
[in] The name of an interface you want to expose from your object.

*x2*<br/>
[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

[!code-cpp[NVC_ATL_Windowing#118](../../atl/codesnippet/cpp/com-map-macros_2.h)]

## <a name="com_interface_entry_iid"></a> 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*<br/>
[in] The GUID of the interface exposed.

*x*<br/>
[in] The name of the class whose vtable will be exposed as the interface identified by *iid*.

### Example

[!code-cpp[NVC_ATL_Windowing#117](../../atl/codesnippet/cpp/com-map-macros_3.h)]

## <a name="com_interface_entry2_iid"></a> COM_INTERFACE_ENTRY2_IID

Same as [COM_INTERFACE_ENTRY2](#com_interface_entry2), except you can specify a different IID.

```
COM_INTERFACE_ENTRY2_IID(iid, x, x2)
```

### Parameters

*iid*<br/>
[in] The GUID you are specifying for the interface.

*x*<br/>
[in] The name of an interface that your class object derives from directly.

*x2*<br/>
[in] The name of a second interface that your class object derives from directly.

## <a name="com_interface_entry_aggregate"></a> 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*<br/>
[in] The GUID of the interface queried for.

*punk*<br/>
[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

[!code-cpp[NVC_ATL_Windowing#112](../../atl/codesnippet/cpp/com-map-macros_4.h)]

## <a name="com_interface_entry_aggregate_blind"></a> COM_INTERFACE_ENTRY_AGGREGATE_BLIND

Same as [COM_INTERFACE_ENTRY_AGGREGATE](#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*<br/>
[in] The name of an `IUnknown` pointer.

### Remarks

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

### Example

[!code-cpp[NVC_ATL_Windowing#113](../../atl/codesnippet/cpp/com-map-macros_5.h)]

## <a name="com_interface_entry_autoaggregate"></a> COM_INTERFACE_ENTRY_AUTOAGGREGATE

Same as [COM_INTERFACE_ENTRY_AGGREGATE](#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*<br/>
[in] The GUID of the interface queried for.

*punk*<br/>
[in] The name of an `IUnknown` pointer. Must be a member of the class containing the COM map.

*clsid*<br/>
[in] The identifier of the aggregate that will be created if *punk* is NULL.

### Remarks

### Example

[!code-cpp[NVC_ATL_Windowing#114](../../atl/codesnippet/cpp/com-map-macros_6.h)]

## <a name="com_interface_entry_autoaggregate_blind"></a> COM_INTERFACE_ENTRY_AUTOAGGREGATE_BLIND

Same as [COM_INTERFACE_ENTRY_AUTOAGGREGATE](#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*<br/>
[in] The name of an `IUnknown` pointer. Must be a member of the class containing the COM map.

*clsid*<br/>
[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

[!code-cpp[NVC_ATL_Windowing#115](../../atl/codesnippet/cpp/com-map-macros_7.h)]

## <a name="com_interface_entry_break"></a> COM_INTERFACE_ENTRY_BREAK

Causes your program to call [DebugBreak](/windows/win32/api/debugapi/nf-debugapi-debugbreak) when the specified interface is queried for.

```
COM_INTERFACE_ENTRY_BREAK(x)
```

### Parameters

*x*<br/>
[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`.

## <a name="com_interface_entry_cached_tear_off"></a> 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*<br/>
[in] The GUID of the tear-off interface.

*x*<br/>
[in] The name of the class implementing the interface.

*punk*<br/>
[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

[!code-cpp[NVC_ATL_COM#54](../../atl/codesnippet/cpp/com-map-macros_8.h)]

## <a name="com_interface_entry_tear_off"></a> COM_INTERFACE_ENTRY_TEAR_OFF

Exposes your tear-off interfaces.

```
COM_INTERFACE_ENTRY_TEAR_OFF(iid, x)
```

### Parameters

*iid*<br/>
[in] The GUID of the tear-off interface.

*x*<br/>
[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

[!code-cpp[NVC_ATL_COM#1](../../atl/codesnippet/cpp/com-map-macros_1.h)]

## <a name="com_interface_entry_chain"></a> 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*<br/>
[in] A base class of the current object.

### Remarks

For example, in the following code:

[!code-cpp[NVC_ATL_Windowing#116](../../atl/codesnippet/cpp/com-map-macros_9.h)]

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-cpp[NVC_ATL_Windowing#111](../../atl/codesnippet/cpp/com-map-macros_10.h)]

## <a name="com_interface_entry_func"></a> COM_INTERFACE_ENTRY_FUNC

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

```
COM_INTERFACE_ENTRY_FUNC(iid, dw, func)
```

### Parameters

*iid*<br/>
[in] The GUID of the interface exposed.

*dw*<br/>
[in] A parameter passed through to the *func*.

*func*<br/>
[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.

## <a name="com_interface_entry_func_blind"></a> COM_INTERFACE_ENTRY_FUNC_BLIND

Same as [COM_INTERFACE_ENTRY_FUNC](#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*<br/>
[in] A parameter passed through to the *func*.

*func*<br/>
[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.

## <a name="com_interface_entry_nointerface"></a> 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*<br/>
[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`.
