ATL Macros and Global Functions

 The ATL macros and global functions offer functionality in the following categories:

Aggregation and Class Factory Macros
COM Map Macros and Global Functions
Connection Point Macros and Global Functions
Debugging and Error Reporting Macros and Global Functions
Device Context Global Functions
Event Handling Global Functions
Marshaling Global Functions
Message Map Macros
Object Map Macros
Pixel/HIMETRIC Conversion Global Functions
Property Map Macros
Registry Macros
Stock Property Macros
String Conversion Macros
Window Class Macros

Aggregation and Class Factory Macros
DECLARE_AGGREGATABLEDeclares that your object can be aggregated (the default).
DECLARE_CLASSFACTORYDeclares the class factory to be CComClassFactory, the ATL default class factory.
DECLARE_CLASSFACTORY_EXDeclares your class factory object to be the class factory.
DECLARE_CLASSFACTORY2Declares CComClassFactory2 to be the class factory.
DECLARE_CLASSFACTORY_AUTO_THREADDeclares CComClassFactoryAutoThread to be the class factory.
DECLARE_CLASSFACTORY_SINGLETONDeclares CComClassFactorySingleton to be the class factory.
DECLARE_GET_CONTROLLING_UNKNOWNDeclares a virtual GetControllingUnknown function.
DECLARE_NOT_AGGREGATABLEDeclares that your object cannot be aggregated.
DECLARE_ONLY_AGGREGATABLEDeclares that your object must be aggregated.
DECLARE_POLY_AGGREGATABLEChecks the value of the outer unknown and declares your object aggregatable or not aggregatable, as appropriate.
DECLARE_PROTECT_FINAL_CONSTRUCTProtects the outer object from deletion during construction of an inner object.
COM Map Macros and Global Functions 
AtlInternalQueryInterfaceDelegates to the IUnknown of a nonaggregated object.
BEGIN_COM_MAPMarks the beginning of the COM interface map entries.
COM_INTERFACE_ENTRY and its variationsEnters interfaces into the COM interface map.
END_COM_MAPMarks the end of the COM interface map entries.
Connection Point Macros and Global Functions
AtlAdviseCreates a connection between an object's connection point and a client's sink.
AtlUnadviseTerminates the connection established through AtlAdvise.
BEGIN_CONNECTION_POINT_MAPMarks the beginning of the connection point map entries.
CONNECTION_POINT_ENTRYEnters connection points into the map.
END_CONNECTION_POINT_MAPMarks the end of the connection point map entries.
Debugging and Error Reporting Macros and Global Functions
AtlReportErrorSets up IErrorInfo to provide error details to a client.
AtlTraceGlobal function that sends a formatted message and/or variable values to the dump device.
ATLTRACESends a formatted message and/or variable values to the dump device.
ATLTRACENOTIMPLSends a message to the dump device that the specified function is not implemented.
Device Context Global Functions 
AtlCreateTargetDCCreates a device context.
Event Handling Global Functions 
AtlWaitWithMessageLoopWaits for an object to be signalled, meanwhile dispatching window messages if necessary.
Marshaling Global Functions 
AtlFreeMarshalStreamReleases the marshal data and the IStream pointer.
AtlMarshalPtrInProcCreates a new stream object and marshals the specified interface pointer.
AtlUnmarshalPtrConverts a stream's marshaling data into an interface pointer.
Message Map Macros
BEGIN_MSG_MAPMarks the beginning of the default message map.
ALT_MSG_MAPMarks the beginning of an alternate message map.
MESSAGE_HANDLERMaps a Windows message to a handler function.
MESSAGE_RANGE_HANDLERMaps a contiguous range of Windows messages to a handler function.
COMMAND_HANDLERMaps a WM_COMMAND message to a handler function, based on the notification code and the identifier of the menu item, control, or accelerator.
COMMAND_ID_HANDLERMaps a WM_COMMAND message to a handler function, based on the identifier of the menu item, control, or accelerator.
COMMAND_CODE_HANDLERMaps a WM_COMMAND message to a handler function, based on the notification code.
COMMAND_RANGE_HANDLERMaps a contiguous range of WM_COMMAND messages to a handler function.
NOTIFY_HANDLERMaps a WM_NOTIFY message to a handler function, based on the notification code and the control identifier.
NOTIFY_ID_HANDLERMaps a WM_NOTIFY message to a handler function, based on the control identifier.
NOTIFY_CODE_HANDLERMaps a WM_NOTIFY message to a handler function, based on the notification code.
NOTIFY_RANGE_HANDLERMaps a contiguous range of WM_NOTIFY messages to a handler function.
CHAIN_MSG_MAPChains to the default message map in the base class.
CHAIN_MSG_MAP_MEMBERChains to the default message map in a data member of the class.
CHAIN_MSG_MAP_ALTChains to an alternate message map in the base class.
CHAIN_MSG_MAP_ALT_MEMBERChains to an alternate message map in a data member of the class.
CHAIN_MSG_MAP_DYNAMICChains to the message map in another class at run time.
CHAIN_MSG_MAP_ALT_DYNAMICChains to an alternate message map in another class at run time.
END_MSG_MAPMarks the end of a message map.
Object Map Macros 
BEGIN_OBJECT_MAPMarks the beginning of the ATL object map and initializes the array of object descriptions.
OBJECT_ENTRYEnters an ATL object into the object map, updates the registry, and creates an instance of the object.
END_OBJECT_MAPMarks the end of the ATL object map.
DECLARE_OBJECT_DESCRIPTIONAllows you to specify a class object’s text description, which will be entered into the object map.
Pixel/HIMETRIC Conversion Global Functions 
AtlHiMetricToPixelConverts HIMETRIC units (each unit is 0.01 millimeter) to pixels.
AtlPixelToHiMetricConverts pixels to HIMETRIC units (each unit is 0.01 millimeter).
Property Map Macros 
BEGIN_PROPERTY_MAPMarks the beginning of the ATL property map.
PROP_ENTRYEnters a property description, property DISPID, and property page CLSID into the property map.
PROP_ENTRY_EXEnters a property description, property DISPID, property page CLSID, and IDispatch IID into the property map.
PROP_PAGEEnters a property page CLSID into the property map.
END_PROPERTY_MAPMarks the end of the ATL property map.
Registry Macros
DECLARE_NO_REGISTRYAvoids default ATL registration.
DECLARE_REGISTRYEnters or removes the main object's entry in the system registry.
DECLARE_REGISTRY_RESOURCEFinds the named resource and runs the registry script within it.
DECLARE_REGISTRY_RESOURCEIDFinds the resource identified by an ID number and runs the registry script within it.
Stock Property Macros 
IMPLEMENT_BSTR_STOCKPROPImplements a text stock property for an ATL object.
IMPLEMENT_SMARTPTR_STOCKPROPImplements a stock property that is an interface pointer.
IMPLEMENT_STOCKPROPImplements a stock property.
String Conversion Macros
String Conversion MacrosSet of macros that convert between string types.
DEVMODE and TEXTMETRIC String Conversion MacrosSet of macros that convert the strings within DEVMODE and TEXTMETRIC structures.
Window Class Macros
DECLARE_WND_CLASSAllows you to specify the name of a new window class.
DECLARE_WND_SUPERCLASSAllows you to specify the name of an existing window class on which a new window class will be based.

ALT_MSG_MAP

ALT_MSG_MAP( msgMapID )

Parameters

msgMapID [in] The message map identifier.

Remarks

Marks the beginning of an alternate message map. ATL identifies each message map by a number. The default message map (declared with the BEGIN_MSG_MAP macro) is identified by 0. An alternate message map is identified by msgMapID.

Message maps are used to process messages sent to a window. For example, CContainedWindow allows you to specify the identifier of a message map in the containing object. CContainedWindow::WindowProc then uses this message map to direct the contained window's messages either to the appropriate handler function or to another message map. For a list of macros that declare handler functions, see BEGIN_MSG_MAP.

Always begin a message map with BEGIN_MSG_MAP. You can then declare subsequent alternate message maps. The following example shows the default message map and one alternate message map, each containing one handler function:

BEGIN_MSG_MAP(CMyClass) 
   MESSAGE_HANDLER(WM_PAINT, OnPaint) 
ALT_MSG_MAP(1) 
   MESSAGE_HANDLER(WM_SETFOCUS, OnSetFocus) 
END_MSG_MAP 

The next example shows two alternate message maps. The default message map is empty.

BEGIN_MSG_MAP(CMyClass) 
ALT_MSG_MAP(1) 
   MESSAGE_HANDLER(WM_PAINT, OnPaint) 
   MESSAGE_HANDLER(WM_SETFOCUS, OnSetFocus) 
ALT_MSG_MAP(2) 
   MESSAGE_HANDLER(WM_CREATE, OnCreate) 
END_MSG_MAP 

The END_MSG_MAP macro marks the end of the message map. Note that there is always exactly one instance of BEGIN_MSG_MAP and END_MSG_MAP.

For more information about using message maps in ATL, see Message Maps in the article “ATL Window Classes.”

ATL Macros and Global Functions

See Also MESSAGE_HANDLER, CMessageMap, CDynamicChain


AtlAdvise

HRESULT AtlAdvise( IUnknown* pUnkCP, IUnknown* pUnk, const IID& iid, LPDWORD pdw );

Return Value

A standard HRESULT value.

Parameters

pUnkCP [in] A pointer to the IUnknown of the object the client wants to connect with.

pUnk [in] A pointer to the client's IUnknown.

iid [in] The GUID of the connection point. Typically, this is the same as the outgoing interface managed by the connection point.

pdw [out] A pointer to the cookie that uniquely identifies the connection.

Remarks

Creates a connection between an object's connection point and a client's sink. The sink implements the outgoing interface supported by the connection point. The client uses the pdw cookie to remove the connection by passing it to AtlUnadvise.

ATL Macros and Global Functions

See Also AtlUnadvise


AtlCreateTargetDC

HDC AtlCreateTargetDC( HDC hdc, DVTARGETDEVICE* ptd );

Return Value

Returns the handle to a device context for the device specified in the DVTARGETDEVICE. If no device is specified, returns the handle to the default display device.

Parameters

hdc [in] The existing handle of a device context, or NULL.

ptd [in] A pointer to the DVTARGETDEVICE structure that contains information about the target device.

Remarks

Creates a device context for the device specified in the DVTARGETDEVICE structure. If the structure is NULL and hdc is NULL, creates a device context for the default display device.

If hdc is not NULL and ptd is NULL, the function returns the existing hdc.

ATL Macros and Global Functions


AtlFreeMarshalStream

void AtlFreeMarshalStream( IStream* pStream );

Parameters

pStream [in] A pointer to the IStream interface on the stream used for marshaling.

Remarks

Releases the marshal data in the stream, then releases the stream pointer.

ATL Macros and Global Functions

See Also AtlMarshalPtrInProc


AtlHiMetricToPixel

extern void AtlPixelToHiMetric( const SIZEL* lpSizeInHiMetric, LPSIZEL lpSizeInPix );

Parameters

lpSizeInHiMetric [in] Pointer to the size of the object in HIMETRIC units.

lpSizeInPix [out] Pointer to where the object's size in pixels is to be returned.

Remarks

Converts an object's size in HIMETRIC units (each unit is 0.01 millimeter) to a size in pixels on the screen device.

ATL Macros and Global Functions

See Also AtlPixelToHiMetric


AtlInternalQueryInterface

HRESULT AtlInternalQueryInterface( void* pThis, const _ATL_INTMAP_ENTRY* pEntries, REFIID iid, void** ppvObject );

Return Value

One of the standard HRESULT values.

Parameters

pThis [in] A pointer to the object that contains the COM map. of interfaces exposed to QueryInterface.

pEntries [in] An array of _ATL_INTMAP_ENTRY structures that access a map of available interfaces.

iid [in] The GUID of the interface being requested.

ppvObject [out] A pointer to the interface pointer specified in iid, or NULL if the interface is not found.

Remarks

Retrieves a pointer to the requested interface.

AtlInternalQueryInterface only handles interfaces in the COM map table. If your object is aggregated, AtlInternalQueryInterface does not delegate to the outer unknown. You can enter interfaces into the COM map table with the macro COM_INTERFACE_ENTRY or one of its variants.

ATL Macros and Global Functions

See Also CComObjectRootEx::InternalAddRef, CComObjectRootEx::InternalRelease


AtlMarshalPtrInProc

HRESULT AtlMarshalPtrInProc( IUnknown* pUnk, const IID& iid, IStream** ppStream );

Return Value

A standard HRESULT value.

Parameters

pUnk [in] A pointer to the interface to be marshaled.

iid [in] The GUID of the interface being marshaled.

ppStream [out] A pointer to the IStream interface on the new stream object that will be used for marshaling.

Remarks

Creates a new stream object, writes the CLSID of the proxy to the stream, and marshals the specified interface pointer by writing the data needed to initialize the proxy into the stream. The MSHLFLAGS_TABLESTRONG flag is set so the pointer can be marshaled to multiple streams. The pointer can also be unmarshaled multiple times.

If marshaling fails, the stream pointer is released.

AtlMarshalPtrInProc can only be used on a pointer to an on-process object.

ATL Macros and Global Functions

See Also AtlUnmarshalPtr, AtlFreeMarshalStream, MSHLFLAGS in the Win32 SDK


AtlPixelToHiMetric

extern void AtlPixelToHiMetric( const SIZEL* lpSizeInPix, LPSIZEL lpSizeInHiMetric );

Parameters

lpSizeInPix [in] Pointer to the object's size in pixels.

lpSizeInHiMetric [out] Pointer to where the object's size in HIMETRIC units is to be returned.

Remarks

Converts an object's size in pixels on the screen device to a size in HIMETRIC units (each unit is 0.01 millimeter).

ATL Macros and Global Functions

See Also AtlHiMetricToPixel


AtlReportError

HRESULT WINAPI AtlReportError( const CLSID& clsid, LPCOLESTR lpszDesc, const IID& iid = GUID_NULL, HRESULT hRes = 0 );

HRESULT WINAPI AtlReportError( const CLSID& clsid, LPCOLESTR lpszDesc, DWORD dwHelpID, LPCOLESTR lpszHelpFile, const IID& iid = GUID_NULL, HRESULT hRes = 0 );

HRESULT WINAPI AtlReportError( const CLSID& clsid, LPCSTR lpszDesc, const IID& iid = GUID_NULL, HRESULT hRes = 0 );

HRESULT WINAPI AtlReportError( const CLSID& clsid, LPCSTR lpszDesc, DWORD dwHelpID, LPCSTR lpszHelpFile, const IID& iid = GUID_NULL, HRESULT hRes = 0, HINSTANCE hInst = _Module.GetResourceInstance( ) );

HRESULT WINAPI AtlReportError( const CLSID& clsid, UINT nID, const IID& iid = GUID_NULL, HRESULT hRes = 0 );

HRESULT WINAPI AtlReportError( const CLSID& clsid, UINT nID, DWORD dwHelpID, LPCOLESTR lpszHelpFile, const IID& iid = GUID_NULL, HRESULT hRes = 0, HINSTANCE hInst = _Module.GetResourceInstance( ) );

Return Value

If the hRes parameter is nonzero, returns the value of hRes . If hRes is zero, the first four versions of AtlReportError return DISP_E_EXCEPTION. The last two versions return the result of the macro MAKE_HRESULT( 1, FACILITY_ITF, nID ).

Parameters

clsid [in] The CLSID of the object reporting the error.

lpszDesc [in] The string describing the error. The Unicode version specifies that lpszDesc is of type LPCOLESTR; the ANSI version specifies a type of LPCSTR.

iid [in] The IID of the interface defining the error or GUID_NULL if the error is defined by the operating system.

hRes [in] An HRESULT you want returned to the caller.

nID [in] The resource identifier where the error description string is stored. The value of nID should lie between 0x0200 and 0xFFFF, inclusively. In debug builds, an ASSERT will result if nID does not index a valid string. In release builds, the error description string will be set to “Unknown Error.”

dwHelpID [in] The help context identifier for the error.

lpszHelpFile [in] The path and name of the help file describing the error.

hInst [in] The handle to the resource. By default, this parameter is _Module::GetResourceInstance, where _Module is the global instance of CComModule or a class derived from it.

Remarks

Sets up the IErrorInfo interface to provide error information to clients of the object. The string lpszDesc is used as the text description of the error. When the client receives the hRes you return from AtlReportError, the client can access the IErrorInfo structure for details about the error.

ATL Macros and Global Functions

See Also IErrorInfo in the Win32 SDK


AtlTrace

void _cdecl AtlTrace( LPCTSTR lpszFormat, ...);

Parameters

lpszFormat [in] The format of the string and variables to send to the dump device.

Remarks

Sends the specified string to the dump device. AtlTrace is available in both debug and release builds.

For example:

AtlTrace(_T(“The value of x is %d.\n”), x);

ATL Macros and Global Functions

See Also ATLTRACE


ATLTRACE

ATLTRACE( exp )

Parameters

exp [in] The formatted string and variables to send to the dump device.

Remarks

Sends the specified string to the dump device. The ATLTRACE macro performs the same as the global function AtlTrace, except that in release builds ATLTRACE compiles to (void) 0, while the function AtlTrace can still be used.

For example:

ATLTRACE(_T(“The value of x is %d.\n”), x)

ATL Macros and Global Functions

See Also AtlTrace


ATLTRACENOTIMPL

ATLTRACENOTIMPL( funcname )

Parameters

funcname [in] A string containing the name of the function that is not implemented.

Remarks

In debug builds of ATL, sends the string "funcname is not implemented" to the dump device and returns E_NOTIMPL. In release builds, returns E_NOTIMPL.

ATL Macros and Global Functions

See Also ATLTRACE


AtlUnadvise

HRESULT AtlUnadvise( IUnknown* pUnkCP, const IID& iid, DWORD dw );

Return Value

A standard HRESULT value.

Parameters

pUnkCP [in] A pointer to the IUnknown of the object that the client is connected with.

iid [in] The GUID of the connection point. Typically, this is the same as the outgoing interface managed by the connection point.

dw [in] The cookie that uniquely identifies the connection.

Remarks

Terminates the connection established through AtlAdvise.

ATL Macros and Global Functions

See Also AtlAdvise


AtlUnmarshalPtr

HRESULT AtlUnmarshalPtr( IStream* pStream, const IID& iid, IUnknown** ppUnk, );

Return Value

A standard HRESULT value.

Parameters

pStream [in] A pointer to the stream being unmarshaled.

iid [in] The GUID of the interface being unmarshaled.

ppUnk [out] A pointer to the unmarshaled interface.

Remarks

Converts the stream's marshaling data into an interface pointer that can be used by the client.

ATL Macros and Global Functions

See Also AtlMarshalPtrInProc


AtlWaitWithMessageLoop

BOOL AtlWaitWithMessageLoop( HANDLE hEvent );

Return Value

Returns TRUE if the object has been signalled.

Parameters

hEvent [in] The handle of the object to wait for.

Remarks

Waits for the object to be signalled, meanwhile dispatching window messages if necessary. This is useful if you want to wait for an object's event to happen and be notified when the event happens, but allow window messages to be dispatched while waiting.

ATL Macros and Global Functions


BEGIN_COM_MAP

BEGIN_COM_MAP( x )

Parameters

x [in] The name of the class object you are exposing interfaces on.

Remarks

The COM map is the mechanism that exposes interfaces on an object to a client through QueryInterface. CComObjectRootEx::InternalQueryInterface only returns pointers for interfaces in the COM map. Start your interface map with the BEGIN_COM_MAP macro, add entries for each of your interfaces with the COM_INTERFACE_ENTRY macro or one of its variants, and complete the map with the END_COM_MAP macro.

For example, from the ATL BEEPER sample:

BEGIN_COM_MAP(CBeeper) 
   COM_INTERFACE_ENTRY(IDispatch) 
   COM_INTERFACE_ENTRY(IBeeper) 
   COM_INTERFACE_ENTRY_TEAR_OFF(IID_ISupportErrorInfo, CBeeper2) 
END_COM_MAP( ) 

See the ATL COMMAP sample for examples using the different types of COM map entry macros.

ATL Macros and Global Functions


BEGIN_CONNECTION_POINT_MAP

BEGIN_CONNECTION_POINT_MAP( x )

Parameters

x [in] The name of the class containing the connection points.

Remarks

Marks the beginning of the connection point map entries. Start your connection point map with the BEGIN_CONNECTION_POINT_MAP macro, add entries for each of your connection points with the CONNECTION_POINT_ENTRY macro, and complete the map with the END_CONNECTION_POINT_MAP macro.

For example:

BEGIN_CONNECTION_POINT_MAP(CConnect) 
   CONNECTION_POINT_ENTRY(m_cpInterfaceBeingExposed) 
END_CONNECTION_POINT_MAP( ) 

For more information about connection points in ATL, see the article Connection Points.

ATL Macros and Global Functions


BEGIN_MSG_MAP

BEGIN_MSG_MAP( theClass )

Parameters

theClass [in] The name of the class containing the message map.

Remarks

Marks the beginning of the default message map. CWindowImpl::WindowProc uses the default message map to process messages sent to the window. The message map directs messages either to the appropriate handler function or to another message map.

The following macros map a message to a handler function. This function must be defined in theClass.

MacroDescription
MESSAGE_HANDLERMaps a Windows message to a handler function.
MESSAGE_RANGE_HANDLERMaps a contiguous range of Windows messages to a handler function.
COMMAND_HANDLERMaps a WM_COMMAND message to a handler function, based on the notification code and the identifier of the menu item, control, or accelerator.
COMMAND_ID_HANDLERMaps a WM_COMMAND message to a handler function, based on the identifier of the menu item, control, or accelerator.
COMMAND_CODE_HANDLERMaps a WM_COMMAND message to a handler function, based on the notification code.
COMMAND_RANGE_HANDLERMaps a contiguous range of WM_COMMAND messages to a handler function, based on the identifier of the menu item, control, or accelerator.
NOTIFY_HANDLERMaps a WM_NOTIFY message to a handler function, based on the notification code and the control identifier.
NOTIFY_ID_HANDLERMaps a WM_NOTIFY message to a handler function, based on the control identifier.
NOTIFY_CODE_HANDLERMaps a WM_NOTIFY message to a handler function, based on the notification code.
NOTIFY_RANGE_HANDLERMaps a contiguous range of WM_NOTIFY messages to a handler function, based on the control identifier.

The following macros direct a message to another message map. This process is called “chaining.”

MacroDescription
CHAIN_MSG_MAPChains to the default message map in the base class.
CHAIN_MSG_MAP_MEMBERChains to the default message map in a data member of the class.
CHAIN_MSG_MAP_ALTChains to an alternate message map in the base class.
CHAIN_MSG_MAP_ALT_MEMBERChains to an alternate message map in a data member of the class.
CHAIN_MSG_MAP_DYNAMICChains to the default message map in another class at run time.
CHAIN_MSG_MAP_ALT_DYNAMICChains to an alternate message map in another class at run time.

Example

class CMyWindow : ... 
{ 
public: 
   ... 
   BEGIN_MSG_MAP(CMyWindow) 
      MESSAGE_HANDLER(WM_PAINT, OnPaint) 
      MESSAGE_HANDLER(WM_SETFOCUS, OnSetFocus) 
      CHAIN_MSG_MAP(CMyBaseWindow) 
   END_MSG_MAP 
   LRESULT OnPaint(UINT uMsg, WPARAM wParam, 
                   LPARAM lParam, BOOL& bHandled) 
   { ... } 
   LRESULT OnSetFocus(UINT uMsg, WPARAM wParam, 
                      LPARAM lParam, BOOL& bHandled) 
   { ... } 
}; 

When a CMyWindow object receives a WM_PAINT message, the message is directed to CMyWindow::OnPaint for the actual processing. If OnPaint indicates the message requires further processing, the message will then be directed to the default message map in CMyBaseWindow.

In addition to the default message map, you can define an alternate message map with ALT_MSG_MAP. Always begin a message map with BEGIN_MSG_MAP. You can then declare subsequent alternate message maps. The following example shows the default message map and one alternate message map, each containing one handler function:

BEGIN_MSG_MAP(CMyClass) 
   MESSAGE_HANDLER(WM_PAINT, OnPaint) 
ALT_MSG_MAP(1) 
   MESSAGE_HANDLER(WM_SETFOCUS, OnSetFocus) 
END_MSG_MAP 

The next example shows two alternate message maps. The default message map is empty.

BEGIN_MSG_MAP(CMyClass) 
ALT_MSG_MAP(1) 
   MESSAGE_HANDLER(WM_PAINT, OnPaint) 
   MESSAGE_HANDLER(WM_SETFOCUS, OnSetFocus) 
ALT_MSG_MAP(2) 
   MESSAGE_HANDLER(WM_CREATE, OnCreate) 
END_MSG_MAP 

The END_MSG_MAP macro marks the end of the message map. Note that there is always exactly one instance of BEGIN_MSG_MAP and END_MSG_MAP.

For more information about using message maps in ATL, see Message Maps in the article “ATL Window Classes.”

ATL Macros and Global Functions

See Also CMessageMap, CDynamicChain


BEGIN_OBJECT_MAP

BEGIN_OBJECT_MAP( x )

Parameters

x [in] Array of ATL object definitions.

Remarks

Marks the beginning of the map of ATL objects. The parameter x is an array holding _ATL_OBJMAP_ENTRY structures that describe the objects.

Start your object map with the BEGIN_OBJECT_MAP macro, add entries for each object with the OBJECT_ENTRY macro, and complete the map with the END_OBJECT_MAP macro. When CComModule::RegisterServer is called, it updates the system registry for each object in the object map.

Typically, you follow an object map definition with CComModule::Init to initialize the instance. For example, from the CIRCCOLL sample:

BEGIN_OBJECT_MAP(ObjectMap)
   OBJECT_ENTRY(CLSID_MyCircleCollectionCreator, CMyCircleCollectionCreator) 
END_OBJECT_MAP( ) 
//DLL Entry Point 
extern “C” 
BOOL WINAPI DllMain(HINSTANCE hInstance, DWORD dwReason, LPVOID /*lpReserved*/) 
{ 
   if (dwReason == DLL_PROCESS_ATTACH) 
   { 
      _Module.Init(ObjectMap, hInstance); 
      DisableThreadLibraryCalls(hInstance); 
   } 
   else if (dwReason == DLL_PROCESS_DETACH) 
      _Module.Term(); 
   return TRUE; 
} 

ATL Macros and Global Functions

See Also OBJECT_ENTRY, END_OBJECT_MAP, CComModule::Init


BEGIN_PROPERTY_MAP

BEGIN_PROPERTY_MAP( theClass )

Parameters

theClass [in] The name of the class containing the property map.

Remarks

Marks the beginning of the object’s property map. The property map stores property descriptions, property DISPIDs, property page CLSIDs, and IDispatch IIDs. Classes IPerPropertyBrowsingImpl, IPersistPropertyBagImpl, IPersistStreamInitImpl, and ISpecifyPropertyPagesImpl use the property map to retrieve and set this information.

When you create a control with the ATL Object Wizard, the wizard will create an empty property map by specifying BEGIN_PROPERTY_MAP followed by END_PROPERTY_MAP.

Example

From the CIRC sample:

BEGIN_PROPERTY_MAP( CCircCtl )
   PROP_ENTRY( "Caption", DISPID_CAPTION, 
               CLSID_CCircProps )
   PROP_ENTRY( "Enabled", DISPID_ENABLED, 
               CLSID_CCircProps )
   PROP_ENTRY( "Fore Color", DISPID_FORECOLOR, 
               CLSID_StockColorPage )
   PROP_ENTRY( "Back Color", DISPID_BACKCOLOR, 
               CLSID_StockColorPage )
   PROP_ENTRY( "Font", DISPID_FONT, CLSID_StockFontPage )
END_PROPERTY_MAP( )

ATL Macros and Global Functions

See Also PROP_ENTRY, PROP_ENTRY_EX, PROP_PAGE


CHAIN_MSG_MAP

CHAIN_MSG_MAP( theChainClass )

Parameters

theChainClass [in] The name of the base class containing the message map.

Remarks

Defines an entry in a message map. CHAIN_MSG_MAP directs messages to a base class's default message map (declared with BEGIN_MSG_MAP). To direct messages to a base class's alternate message map (declared with ALT_MSG_MAP), use CHAIN_MSG_MAP_ALT.

For example:

class CMyClass : public CMyBaseClass, ... 
{ 
public: 
   ... 
   BEGIN_MSG_MAP(CMyClass) 
      MESSAGE_HANDLER(WM_PAINT, OnPaint) 
      // chain to default message map in CMyBaseClass 
      CHAIN_MSG_MAP(CMyBaseClass) 
   ALT_MSG_MAP(1)  
      // chain to default message map in CMyBaseClass 
      CHAIN_MSG_MAP(CMyBaseClass) 
   ALT_MSG_MAP(2) 
      MESSAGE_HANDLER(WM_CHAR, OnChar) 
      // chain to alternate message map in CMyBaseClass 
      CHAIN_MSG_MAP_ALT(CMyBaseClass, 1) 
   END_MSG_MAP 
   ... 
}; 

This example illustrates the following:

Note Always begin a message map with BEGIN_MSG_MAP. You can then declare subsequent alternate message maps with ALT_MSG_MAP. The END_MSG_MAP macro marks the end of the message map. Every message map must have exactly one instance of BEGIN_MSG_MAP and END_MSG_MAP.

For more information about using message maps in ATL, see Message Maps in the article “ATL Window Classes.”

ATL Macros and Global Functions

See Also CHAIN_MSG_MAP_MEMBER, CHAIN_MSG_MAP_DYNAMIC, MESSAGE_HANDLER


CHAIN_MSG_MAP_ALT

CHAIN_MSG_MAP_ALT( theChainClass, msgMapID )

Parameters

theChainClass [in] The name of the base class containing the message map.

msgMapID [in] The message map identifier.

Remarks

Defines an entry in a message map. CHAIN_MSG_MAP_ALT directs messages to an alternate message map in a base class. You must have declared this alternate message map with ALT_MSG_MAP(msgMapID). To direct messages to a base class's default message map (declared with BEGIN_MSG_MAP), use CHAIN_MSG_MAP. For an example, see CHAIN_MSG_MAP.

Note Always begin a message map with BEGIN_MSG_MAP. You can then declare subsequent alternate message maps with ALT_MSG_MAP. The END_MSG_MAP macro marks the end of the message map. Every message map must have exactly one instance of BEGIN_MSG_MAP and END_MSG_MAP.

For more information about using message maps in ATL, see Message Maps in the article “ATL Window Classes.”

ATL Macros and Global Functions

See Also CHAIN_MSG_MAP_ALT_MEMBER, CHAIN_MSG_MAP_ALT_DYNAMIC


CHAIN_MSG_MAP_ALT_DYNAMIC

CHAIN_MSG_MAP_ALT_DYNAMIC( dynaChainID, msgMapID )

Parameters

dynaChainID [in] The unique identifier for an object and its message map.

msgMapID [in] The message map identifier.

Remarks

Defines an entry in a message map. CHAIN_MSG_MAP_ALT_DYNAMIC directs messages, at run time, to an alternate message map in another object. You must have declared this alternate message map with ALT_MSG_MAP(msgMapID).

The chained object and its message map are associated with the dynaChainID value, which you define through CDynamicChain::SetChainEntry. You must derive your class from CDynamicChain in order to use CHAIN_MSG_MAP_ALT_DYNAMIC.

To direct messages at run time to another object's default message map (declared with BEGIN_MSG_MAP), use CHAIN_MSG_MAP_DYNAMIC. For an example, see the CDynamicChain overview.

Note Always begin a message map with BEGIN_MSG_MAP. You can then declare subsequent alternate message maps with ALT_MSG_MAP. The END_MSG_MAP macro marks the end of the message map. Every message map must have exactly one instance of BEGIN_MSG_MAP and END_MSG_MAP.

For more information about using message maps in ATL, see Message Maps in the article “ATL Window Classes.”

ATL Macros and Global Functions

See Also CHAIN_MSG_MAP_ALT, CHAIN_MSG_MAP_ALT_MEMBER


CHAIN_MSG_MAP_ALT_MEMBER

CHAIN_MSG_MAP_ALT_MEMBER( theChainMember, msgMapID )

Parameters

theChainMember [in] The name of the data member containing the message map.

msgMapID [in] The message map identifier.

Remarks

Defines an entry in a message map. CHAIN_MSG_MAP_ALT_MEMBER directs messages to an alternate message map in a data member. You must have declared this alternate message map with ALT_MSG_MAP(msgMapID). To direct messages to a data member's default message map (declared with BEGIN_MSG_MAP), use CHAIN_MSG_MAP_MEMBER. For an example, see CHAIN_MSG_MAP_MEMBER.

Note Always begin a message map with BEGIN_MSG_MAP. You can then declare subsequent alternate message maps with ALT_MSG_MAP. The END_MSG_MAP macro marks the end of the message map. Every message map must have exactly one instance of BEGIN_MSG_MAP and END_MSG_MAP.

For more information about using message maps in ATL, see Message Maps in the article “ATL Window Classes.”

ATL Macros and Global Functions

See Also CHAIN_MSG_MAP_ALT, CHAIN_MSG_MAP_ALT_DYNAMIC


CHAIN_MSG_MAP_DYNAMIC

CHAIN_MSG_MAP_DYNAMIC( dynaChainID )

Parameters

dynaChainID [in] The unique identifier for an object's message map.

Remarks

Defines an entry in a message map. CHAIN_MSG_MAP_DYNAMIC directs messages, at run time, to the default message map in another object. The object and its message map are associated with dynaChainID, which you define through CDynamicChain::SetChainEntry. You must derive your class from CDynamicChain in order to use CHAIN_MSG_MAP_DYNAMIC. For an example, see the CDynamicChain overview.

To direct messages at run time to another object's alternate message map (declared with ALT_MSG_MAP), use CHAIN_MSG_MAP_ALT_DYNAMIC.

Note Always begin a message map with BEGIN_MSG_MAP. You can then declare subsequent alternate message maps with ALT_MSG_MAP. The END_MSG_MAP macro marks the end of the message map. Every message map must have exactly one instance of BEGIN_MSG_MAP and END_MSG_MAP.

For more information about using message maps in ATL, see Message Maps in the article “ATL Window Classes.”

ATL Macros and Global Functions

See Also CHAIN_MSG_MAP, CHAIN_MSG_MAP_MEMBER


CHAIN_MSG_MAP_MEMBER

CHAIN_MSG_MAP_MEMBER( theChainMember )

Parameters

theChainMember [in] The name of the data member containing the message map.

Remarks

Defines an entry in a message map. CHAIN_MSG_MAP_MEMBER directs messages to a data member's default message map (declared with BEGIN_MSG_MAP). To direct messages to a data member's alternate message map (declared with ALT_MSG_MAP), use CHAIN_MSG_MAP_ALT_MEMBER.

For example:

class CMyClass : ... 
{ 
public: 
   CMyContainedClass m_obj; 
   ... 
   BEGIN_MSG_MAP(CMyClass) 
      MESSAGE_HANDLER(WM_PAINT, OnPaint) 
      // chain to default message map of m_obj 
      CHAIN_MSG_MAP_MEMBER(m_obj) 
   ALT_MSG_MAP(1) 
      // chain to default message map of m_obj 
      CHAIN_MSG_MAP(m_obj) 
   ALT_MSG_MAP(2) 
      MESSAGE_HANDLER(WM_CHAR, OnChar) 
      // chain to alternate message map of m_obj 
      CHAIN_MSG_MAP_ALT(m_obj, 1) 
   END_MSG_MAP 
   ... 
}; 

This example illustrates the following:

Note Always begin a message map with BEGIN_MSG_MAP. You can then declare subsequent alternate message maps with ALT_MSG_MAP. The END_MSG_MAP macro marks the end of the message map. Every message map must have exactly one instance of BEGIN_MSG_MAP and END_MSG_MAP.

For more information about using message maps in ATL, see Message Maps in the article “ATL Window Classes.”

ATL Macros and Global Functions

See Also CHAIN_MSG_MAP, CHAIN_MSG_MAP_DYNAMIC, MESSAGE_HANDLER


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.

Each object that wants to expose its interfaces via QueryInterface must have its own COM map. The COM map starts with the macro BEGIN_COM_MAP (classname_of_object). Interface entries are added with one or more of the COM_INTERFACE_ENTRY macro, and the map is completed with the END_COM_MAP macro. For example:

BEGIN_COM_MAP(CMyObject)
   COM_INTERFACE_ENTRY(IDispatch)
   COM_INTERFACE_ENTRY(IMyObject)
END_COM_MAP( )

See the ATL COMMAP sample for examples using the different types of COM map entry macros.

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(COtherObject)
END_COM_MAP( )

The following are the available COM map entry macros:

COM Map Entry Macros
COM_INTERFACE_ENTRY
COM_INTERFACE_ENTRY_IID
COM_INTERFACE_ENTRY2
COM_INTERFACE_ENTRY2_IID
COM_INTERFACE_ENTRY_IMPL
COM_INTERFACE_ENTRY_IMPL_IID
COM_INTERFACE_ENTRY_FUNC
COM_INTERFACE_ENTRY_FUNC_BLIND
COM_INTERFACE_ENTRY_TEAR_OFF
COM_INTERFACE_ENTRY_CACHED_TEAR_OFF
COM_INTERFACE_ENTRY_AGGREGATE
COM_INTERFACE_ENTRY_AGGREGATE_BLIND
COM_INTERFACE_ENTRY_AUTOAGGREGATE
COM_INTERFACE_ENTRY_AUTOAGGREGATE_BLIND
COM_INTERFACE_ENTRY_CHAIN
COM_INTERFACE_ENTRY_BREAK
COM_INTERFACE_ENTRY_NOINTERFACE

ATL Macros and Global Functions


COM_INTERFACE_ENTRY( x )

Parameters

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

Remarks

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

For example:

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

See COM_INTERFACE_ENTRY Macros for remarks about COM map entries.

ATL Macros and Global Functions


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

Use this macro to disambiguate two branches of inheritance. 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.

For example, from the ATL sample COMMAP:

class COuter : 
   public CChainBase, // CChainBase derives from IDispatch
   public CComDualImpl<IOuter, &IID_IOuter, &LIBID_COMMAPLib>, 
   public CComCoClass<COuter,&CLSID_COuter>
{
public:
   COuter(){}
   ...
   BEGIN_COM_MAP(COuter)
      COM_INTERFACE_ENTRY2(IDispatch, IOuter)
   ...
   END_COM_MAP()
};

See COM_INTERFACE_ENTRY Macros for remarks about COM map entries.

ATL Macros and Global Functions


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.

Remarks

As COM_INTERFACE_ENTRY2, except you can specify a different IID.

See COM_INTERFACE_ENTRY Macros for remarks about COM map entries.

ATL Macros and Global Functions


COM_INTERFACE_ENTRY_AGGREGATE( iid, punk )

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.

Remarks

When the interface identified by iid is queried for, COM_INTERFACE_ENTRY_AGGREGATE forwards it to punk. 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.

For example, from the ATL sample COMMAP:

BEGIN_COM_MAP(COuter)
...
   COM_INTERFACE_ENTRY_AGGREGATE(IID_IAgg, m_pUnkAgg.p)
...
END_COM_MAP()

See COM_INTERFACE_ENTRY Macros for remarks about COM map entries.

ATL Macros and Global Functions


COM_INTERFACE_ENTRY_AGGREGATE_BLIND( punk )

Parameters

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

Remarks

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

For example, from the ATL sample COMMAP:

BEGIN_COM_MAP(COuter)
...
   COM_INTERFACE_ENTRY_AGGREGATE_BLIND(m_pUnkAggBlind.p)
...
END_COM_MAP()

See COM_INTERFACE_ENTRY Macros for remarks about COM map entries.

ATL Macros and Global Functions


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

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

For example, from the ATL sample COMMAP:

BEGIN_COM_MAP(COuter)
...
   COM_INTERFACE_ENTRY_AUTOAGGREGATE(IID_IAutoAgg, m_pUnkAutoAgg.p, CLSID_CAutoAgg)
...
END_COM_MAP()

See COM_INTERFACE_ENTRY Macros for remarks about COM map entries.

ATL Macros and Global Functions


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

Same as COM_INTERFACE_ENTRY_AUTOAGGREGATE, except that querying for any IID resulte in forwarding the query to punk, and if punk is NULL, automatically creating the aggregate described by the clsid. If the interface query fails, processing of the COM map continues.

For example, from the ATL sample COMMAP:

BEGIN_COM_MAP(COuter)
...
   COM_INTERFACE_ENTRY_AUTOAGGREGATE_BLIND(m_pUnkAutoAggB.p, CLSID_CAutoAggB)
...
END_COM_MAP()

See COM_INTERFACE_ENTRY Macros for remarks about COM map entries.

ATL Macros and Global Functions


COM_INTERFACE_ENTRY_BREAK

COM_INTERFACE_ENTRY_BREAK( x )

Parameters

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

Remarks

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

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

See COM_INTERFACE_ENTRY Macros for remarks about COM map entries.

ATL Macros and Global Functions


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

Saves the interface specific data for every instance If the interface is not used, this lowers the overall instance size of your object.

For example, from the ATL sample COMMAP:

BEGIN_COM_MAP(COuter)
...
   COM_INTERFACE_ENTRY_CACHED_TEAR_OFF(IID_ITearOff2, CTearOff2, m_pUnkTearPff2.p)
...
END_COM_MAP()

See COM_INTERFACE_ENTRY Macros for remarks about COM map entries.

ATL Macros and Global Functions


COM_INTERFACE_ENTRY_CHAIN( classname )

Parameters

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

Remarks

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

For example, from the ATL sample COMMAP:

BEGIN_COM_MAP(COuter)
   COM_INTERFACE_ENTRY2(IDispatch, IOuter)
...
   COM_INTERFACE_ENTRY_CHAIN(CChainBase)
...
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(COtherObject)
END_COM_MAP( )

See COM_INTERFACE_ENTRY Macros for remarks about COM map entries.

ATL Macros and Global Functions


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

A general mechanism for hooking into ATL's QueryInterface logic. 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 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.

See COM_INTERFACE_ENTRY Macros for remarks about COM map entries.

ATL Macros and Global Functions


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

Same as COM_INTERFACE_ENTRY_FUNC, except that querying for any IID results in a call to func. Any failure will cause processing to continue on the COM map. If the function returns an interface pointer, it should return S_OK.

See COM_INTERFACE_ENTRY Macros for remarks about COM map entries.

ATL Macros and Global Functions


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.

Remarks

Use this macro to enter the interface into the COM map and specify its IID.

For example:

BEGIN_COM_MAP(CThisExample)
   COM_INTERFACE_ENTRY_IID(*piid, CThisExample)
   COM_INTERFACE_ENTRY(IDispatch)
   COM_INTERFACE_ENTRY(IThisExample)
   COM_INTERFACE_ENTRY(ISupportErrorInfo)
END_COM_MAP()

See COM_INTERFACE_ENTRY Macros for remarks about COM map entries.

ATL Macros and Global Functions


COM_INTERFACE_ENTRY_IMPL( x )

Parameters

x [in] A name that will be used to construct the interface ID (IID) and to construct the name of the class whose vtable entries will be exposed.

Remarks

Use this macro to construct the IID, construct the interface name, and enter the interface into the COM map.

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

The class name is constructed by aopending Impl to x and then appending a templatization on the object exposing the class through its COM map. For example, if x is IPersistStorage and the object exposing the class is CThisCtl , the class name will be IPersistStorageImpl<CThisCtl>.

Use COM_INTERFACE_ENTRY_IMPL to construct a class that has the same vtable as a needed interface but is templatized on the object exposing that interface though its COM map. While you can accomplish the same thing by coding COM_INTERFACE_ENTRY_IID(IID_x, xImpl<CThisCtl>), COM_INTERFACE_ENTRY_IMPL is more convenient.

For example:

class CCircCtl : 
   ... 
   public IPersistStreamInitImpl<CCircCtl>, 
   public IPersistStorageImpl<CCircCtl>, 
   ... 
{
public:
   ...
   BEGIN_COM_MAP(CCircCtl)
      ... 
      COM_INTERFACE_ENTRY_IMPL(IPersistStorage)
      COM_INTERFACE_ENTRY_IMPL(IPersistStreamInit)
      ...
   END_COM_MAP()
   ...
};

See COM_INTERFACE_ENTRY Macros for remarks about COM map entries.

ATL Macros and Global Functions


COM_INTERFACE_ENTRY_IMPL_IID( iid, x )

Parameters

iid [in] The GUID of the interface exposed.

x [in] A name that will be used to construct the name of the class whose vtable entries will be exposed.

Remarks

Use this macro to specify the interface IID, construct the interface name, and enter the interface into the COM map.

The class name is constructed by prepending x to Impl and a templatization on the object exposing the class through its COM map. For example, if x is IPersistStorage and the object exposing the class is CThisCtl , the class will be IPersistStorageImpl<CThisCtl>.

Use COM_INTERFACE_ENTRY_IMPL_IID to construct a class that has the same vtable as a needed interface but is templatized on the object exposing that interface though its COM map. While you can accomplish the same thing by coding COM_INTERFACE_ENTRY_IID(iid, xImpl<CThisCtl>), COM_INTERFACE_ENTRY_IMPL_IID is more convenient.

For example:

class CCircCtl : 
   ... 
   public IPersistPropertyBagImpl<CCircCtl>,
   ... 
{ 
public:
   ... 
   BEGIN_COM_MAP(CCircCtl) 
      ... 
      COM_INTERFACE_ENTRY_IMPL_IID(IID_IPersist, IPersistPropertyBag)
      ... 
   END_COM_MAP()
   ... 
};

See COM_INTERFACE_ENTRY Macros for remarks about COM map entries.

ATL Macros and Global Functions


COM_INTERFACE_ENTRY_NOINTERFACE

COM_INTERFACE_ENTRY_NOINTERFACE( x )

Parameters

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

Remarks

Returns E_NOINTERFACE and terminates COM map processing when the specified interface is queried for. 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 ID (IID) will be constructed by appending x to IID_. For example, if x is IPersistStorage, the IID will be IID_IPersistStorage.

See COM_INTERFACE_ENTRY Macros for remarks about COM map entries.

ATL Macros and Global Functions


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

Exposes your tear-off interfaces. 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.

For example, from the ATL sample COMMAP:

BEGIN_COM_MAP(COuter)
...
   COM_INTERFACE_ENTRY_TEAR_OFF(IID_ITearOff1, CTearOff1)
...
END_COM_MAP()

See COM_INTERFACE_ENTRY Macros for remarks about COM map entries.

ATL Macros and Global Functions


COMMAND_CODE_HANDLER

COMMAND_CODE_HANDLER( code, func )

Parameters

code [in] The notification code.

func [in] The name of the message-handler function.

Remarks

Similar to COMMAND_HANDLER, but maps a WM_COMMAND message based only on the notification code.

ATL Macros and Global Functions

See Also COMMAND_ID_HANDLER, COMMAND_RANGE_HANDLER, MESSAGE_HANDLER, NOTIFY_CODE_HANDLER


COMMAND_HANDLER

COMMAND_HANDLER( id, code, func )

Parameters

id [in] The identifier of the menu item, control, or accelerator.

code [in] The notification code.

func [in] The name of the message-handler function.

Remarks

Defines an entry in a message map. COMMAND_HANDLER maps a WM_COMMAND message to the specified handler function, based on the notification code and the control identifier. For example:

class CMyClass : ... 
{ 
public: 
   ... 
   BEGIN_MSG_MAP(CMyClass) 
      COMMAND_HANDLER(IDC_MYCTL, EN_CHANGE, OnChange) 
      ... 
   END_MSG_MAP() 
   // When a CMyClass object receives a WM_COMMAND 
   // message identified by IDC_MYCTL and EN_CHANGE, 
   // the message is directed to CMyClass::OnChange 
   // for the actual processing. 
   LRESULT OnChange( ... ) 
   { ... } 
}; 

Any function specified in a COMMAND_HANDLER macro must defined as follows:

LRESULT CommandHandler(WORD wNotifyCode, WORD wID, HWND hWndCtl, BOOL& bHandled);

The message map sets bHandled to TRUE before CommandHandler is called. If CommandHandler does not fully handle the message, it should set bHandled to FALSE to indicate the message needs further processing.

Note Always begin a message map with BEGIN_MSG_MAP. You can then declare subsequent alternate message maps with ALT_MSG_MAP. The END_MSG_MAP macro marks the end of the message map. Every message map must have exactly one instance of BEGIN_MSG_MAP and END_MSG_MAP.

In addition to COMMAND_HANDLER, you can use MESSAGE_HANDLER to map a WM_COMMAND message without regard to an identifier or code. In this case, MESSAGE_HANDLER(WM_COMMAND, OnHandlerFunction) will direct all WM_COMMAND messages to OnHandlerFunction.

For more information about using message maps in ATL, see Message Maps in the article “ATL Window Classes.”

ATL Macros and Global Functions

See Also COMMAND_ID_HANDLER, COMMAND_CODE_HANDLER, COMMAND_RANGE_HANDLER, NOTIFY_HANDLER


COMMAND_ID_HANDLER

COMMAND_ID_HANDLER( id, func )

Parameters

id [in] The identifier of the menu item, control, or accelerator sending the message.

func [in] The name of the message-handler function.

Remarks

Similar to COMMAND_HANDLER, but maps a WM_COMMAND message based only on the identifier of the menu item, control, or accelerator.

ATL Macros and Global Functions

See Also COMMAND_CODE_HANDLER, COMMAND_RANGE_HANDLER, MESSAGE_HANDLER, NOTIFY_ID_HANDLER


COMMAND_RANGE_HANDLER

COMMAND_RANGE_HANDLER( idFirst, idLast, func )

Parameters

idFirst [in] Marks the beginning of a contiguous range of WM_COMMAND messages.

idLast [in] Marks the end of a contiguous range of WM_COMMAND messages.

func [in] The name of the message-handler function.

Remarks

Similar to COMMAND_HANDLER, but maps a range of WM_COMMAND messages to a single handler function. This range is based on the identifier of the menu item, control, or accelerator sending the message.

ATL Macros and Global Functions

See Also COMMAND_ID_HANDLER, COMMAND_CODE_HANDLER, MESSAGE_RANGE_HANDLER, NOTIFY_RANGE_HANDLER


CONNECTION_POINT_ENTRY

CONNECTION_POINT_ENTRY( iid )

Parameters

iid [in] The GUID of the interface being added to the connection point map.

Remarks

Enters a connection point for the specified interface into the connection point map so that it can be accessed. Connection point entries in the map are used by IConnectionPointContainerImpl. The class containing the connection point map must inherit from IConnectionPointContainerImpl. For example:

class CMyCPClass :
public IConnectionPointContainerImpl, 
public IPropertyNotifySinkImpl<CMyCPClass>
... 
BEGIN_CONNECTION_POINT_MAP(CMyCPClass) 
   CONNECTION_POINT_ENTRY(IID_IPropertyNotifySink) 
END_CONNECTION_POINT_MAP( ) 
... 

Start your connection point map with the BEGIN_CONNECTION_POINT_MAP macro, add entries for each of your connection points with the CONNECTION_POINT_ENTRY macro, and complete the map with the END_CONNECTION_POINT_MAP macro.

For more information about connection points in ATL, see the article Connection Points.

ATL Macros and Global Functions


DECLARE_AGGREGATABLE

DECLARE_AGGREGATABLE( x )

Parameters

x [in] The name of the class you are defining as aggregatable.

Remarks

Specifies that your object can be aggregated. CComCoClass contains this macro to specify the default aggregation model. To override this default, specify either the DECLARE_NOT_AGGREGATABLE or DECLARE_ONLY_AGGREGATABLE macro in your class definition. For example:

class CMyClass : public CComCoClass< .. >, ...
{
public:
   DECLARE_NOT_AGGREGATABLE(CMyClass)
   ...
};

ATL Macros and Global Functions


DECLARE_CLASSFACTORY

DECLARE_CLASSFACTORY( )

Remarks

Declares CComClassFactory to be the class factory. CComCoClass uses this macro to declare the default class factory for your object.

ATL Macros and Global Functions

See Also DECLARE_CLASSFACTORY_EX, DECLARE_CLASSFACTORY2, DECLARE_CLASSFACTORY_AUTO_THREAD, DECLARE_CLASSFACTORY_SINGLETON


DECLARE_CLASSFACTORY2

DECLARE_CLASSFACTORY2( lic )

Parameters

lic [in] A class that implements VerifyLicenseKey, GetLicenseKey, and IsLicenseValid.

Remarks

Declares CComClassFactory2 to be the class factory. For example:

class CMyClass : ..., public CComCoClass< ... >
{
   ...
   DECLARE_CLASSFACTORY2(CMyLicense)
   ...
};

CComCoClass includes the DECLARE_CLASSFACTORY macro, which specifies CComClassFactory as the default class factory. However, by including the DECLARE_CLASSFACTORY2 macro in your object’s class definition, you override this default.

ATL Macros and Global Functions

See Also DECLARE_CLASSFACTORY_EX, DECLARE_CLASSFACTORY_AUTO_THREAD, DECLARE_CLASSFACTORY_SINGLETON


DECLARE_CLASSFACTORY_AUTOTHREAD

DECLARE_CLASSFACTORY_AUTO_THREAD( )

Remarks

Declares CComClassFactoryAutoThread to be the class factory. For example:

class CMyClass : ..., public CComCoClass< ... >
{
   ...
   DECLARE_CLASSFACTORY_AUTO_THREAD( )
   ...
};

CComCoClass includes the DECLARE_CLASSFACTORY macro, which specifies CComClassFactory as the default class factory. However, by including the DECLARE_CLASSFACTORY_AUTO_THREAD macro in your object’s class definition, you override this default.

ATL Macros and Global Functions

See Also DECLARE_CLASSFACTORY_EX, DECLARE_CLASSFACTORY2, DECLARE_CLASSFACTORY_SINGLETON


DECLARE_CLASSFACTORY_EX

DECLARE_CLASSFACTORY_EX( cf )

Parameters

cf [in] The name of the class that implements your class factory object.

Remarks

Declares cf to be the class factory. cf must derive from CComClassFactory and override the CreateInstance method. For example:

class CMyClass : ..., public CComCoClass< ... >
{
   ...
   DECLARE_CLASSFACTORY_EX(CMyClassFactory)
   ...
};

CComCoClass includes the DECLARE_CLASSFACTORY macro, which specifies CComClassFactory as the default class factory. However, by including the DECLARE_CLASSFACTORY_EX macro in your object’s class definition, you override this default.

ATL Macros and Global Functions

See Also DECLARE_CLASSFACTORY2, DECLARE_CLASSFACTORY_AUTO_THREAD, DECLARE_CLASSFACTORY_SINGLETON


DECLARE_CLASSFACTORY_SINGLETON

DECLARE_CLASSFACTORY_SINGLETON( obj )

Parameters

obj [in] The name of your class object.

Remarks

Declares CComClassFactorySingleton to be the class factory. For example:

class CMyClass : ..., public CComCoClass< ... >
{
   ...
   DECLARE_CLASSFACTORY_SINGLETON(CMyClass)
   ...
};

CComCoClass includes the DECLARE_CLASSFACTORY macro, which specifies CComClassFactory as the default class factory. However, by including the DECLARE_CLASSFACTORY_SINGLETON macro in your object’s class definition, you override this default.

ATL Macros and Global Functions

See Also DECLARE_CLASSFACTORY2, DECLARE_CLASSFACTORY_EX, DECLARE_CLASSFACTORY_AUTO_THREAD


DECLARE_GET_CONTROLLING_UNKNOWN

DECLARE_GET_CONTROLLING_UNKNOWN( )

Remarks

Declares a virtual function GetControllingUnknown. Add this macro to your object if you get the compiler error message that GetControllingUnknown is undefined, for example, in CComAggregateCreator.

ATL Macros and Global Functions

See Also DECLARE_AGGREGATABLE


DECLARE_NO_REGISTRY

DECLARE_NO_REGISTRY( )

Remarks

Returns S_OK. Use DECLARE_NO_REGISTRY if you want to avoid any default ATL registration for the class in which this macro appears.

ATL Macros and Global Functions

See Also DECLARE_REGISTRY, DECLARE_REGISTRY_RESOURCE , DECLARE_REGISTRY_RESOURCEID


DECLARE_NOT_AGGREGATABLE

DECLARE_NOT_AGGREGATABLE( x )

Parameters

x [in] The name of the class object you are defining as not aggregatable.

Remarks

Specifies that your object cannot be aggregated. DECLARE_NOT_AGGREGATABLE causes CreateInstance to return an error (CLASS_E_NOAGGREGATION) if an attempt is made to aggregate onto your object.

By default, CComCoClass contains the DECLARE_AGGREGATABLE macro, which specifies that your object can be aggregated. To override this default behavior, include DECLARE_NOT_AGGREGATABLE in your class definition. For example:

class CMyClass : public CComCoClass< .. >, ...
{
public:
   DECLARE_NOT_AGGREGATABLE(CMyClass)
   ...
};

ATL Macros and Global Functions

See Also DECLARE_ONLY_AGGREGATABLE


DECLARE_OBJECT_DESCRIPTION

DECLARE_OBJECT_DESCRIPTION( x )

Parameters

x [in] The class object’s description.

Remarks

Allows you to specify a text description for your class object. ATL enters this description into the object map through the OBJECT_ENTRY macro.

DECLARE_OBJECT_DESCRIPTION implements a GetObjectDescription function, which you can use to override the CComCoClass::GetObjectDescription method. For example:

 

class CMyClass : public CComCoClass< ... >, ...
{
public:
   DECLARE_OBJECT_DESCRIPTION("Account Transfer Object 1.0") 
   ...
};

GetObjectDescription is called by IComponentRegistrar::GetComponents. IComponentRegistrar is an Automation interface that allows you to register and unregister individual components in a DLL. When you create a Component Registrar object with the ATL Object Wizard, the wizard will automatically implement the IComponentRegistrar interface. IComponentRegistrar is typically used by Microsoft Transaction Server.

For more information about the ATL Object Wizard, see the article Creating an ATL Project.

ATL Macros and Global Functions


DECLARE_ONLY_AGGREGATABLE

DECLARE_ONLY_AGGREGATABLE( x )

Parameters

x [in] The name of the class object you are defining as only aggregatable.

Remarks

Specifies that your objec must be aggregated. DECLARE_ONLY_AGGREGATABLE causes an error (E_FAIL) if an attempt is made to CoCreate your object as a non-aggregated object.

By default, CComCoClass contains the DECLARE_AGGREGATABLE macro, which specifies that your object can be aggregated. To override this default behavior, include DECLARE_ONLY_AGGREGATABLE in your class definition. For example:

class CMyClass : public CComCoClass< .. >, ...
{
public:
   DECLARE_ONLY_AGGREGATABLE(CMyClass)
   ...
};

ATL Macros and Global Functions

See Also DECLARE_NOT_AGGREGATABLE


DECLARE_POLY_AGGREGATABLE

DECLARE_POLY_AGGREGATABLE( x )

Parameters

x [in] The name of the class object you are defining as aggregatable or not aggregatable.

Remarks

Specifies that an instance of CComPolyObject < x > is created when your object is created. During creation, the value of the outer unknown is checked. If it is NULL, IUnknown is implemented for a nonaggregated object. If the outer unknown is not NULL, IUnknown is implemented for an aggregated object.

The advantage of using DECLARE_POLY_AGGREGATABLE is that you avoid having both CComAggObject and CComObject in your module to handle the aggregated and nonaggregated cases. A single CComPolyObject object handles both cases. This means only one copy of the vtable and one copy of the functions exist in your module. If your vtable is large, this can substantially decrease your module size. However, if your vtable is small, using CComPolyObject can result in a slightly larger module size because it is not optimized for an aggregated or nonaggregated object, as are CComAggObject and CComObject.

The DECLARE_POLY_AGGREGATABLE macro is automatically declared in your object if you use the ATL Object Wizard to create a full control or Internet Explorer control.

ATL Macros and Global Functions

See Also CComPolyObject


DECLARE_PROTECT_FINAL_CONSTRUCT

DECLARE_PROTECT_FINAL_CONSTRUCT( )

Remarks

Protects your object from being deleted if (during FinalConstruct) the internal aggregated object increments the reference count then decrements the count to 0.

ATL Macros and Global Functions

See Also CComObjectRootEx::FinalConstruct


DECLARE_REGISTRY

DECLARE_REGISTRY( class, pid, vpid, nid, flags )

Parameters

class [in] Included for backward compatibility.

pid [in] An LPCTSTR that is a version-specific program identifier.

vpid [in] An LPCTSTR that is a version- independent program identifier.

nid [in] A UINT that is the index of the resource string in the registry to use as the description of the program.

flags [in] A DWORD containing the program's threading model in the registry. One of the following values: _ATL_SINGLE_THREADED, _ATL_APARTMENT_THREADED, or _ATL_FREE_THREADED.

Remarks

Enters the standard class registration into the system registry or removes it from the system registry. The standard registration consists of the CLSID, the program ID, the version-independent program ID, description string, and the thread model.

When you create an object or control with the ATL Object Wizard, the wizard automatically implements script-based registry support and adds the DECLARE_REGISTRY_RESOURCEID macro to your files. If you do not want script-based registry support, replace this macro with DECLARE_REGISTRY. DECLARE_REGISTRY only inserts the five basic keys described above into the registry. You must manually write code to insert other keys into the registry.

ATL Macros and Global Functions

See Also DECLARE_REGISTRY_RESOURCE, DECLARE_REGISTRY_RESOURCEID


DECLARE_REGISTRY_RESOURCE

DECLARE_REGISTRY_RESOURCE( x )

Parameters

x [in] String identifier of your resource.

Remarks

Gets the named resource containing the registry file and runs the script to enter objects into the system registry or remove them from the system registry.

When you create an object or control with the ATL Object Wizard, the wizard automatically implements script-based registry support and adds the DECLARE_REGISTRY_RESOURCEID macro, which is similar to DECLARE_REGISTRY_RESOURCE, to your files.

You can statically link to the ATL Registry Component (Registrar) for optimized registry access. To statically link to the Registrar code, add #define _ATL_STATIC_REGISTRY to your stdafx.h.

If you want ATL to substitute replacement values at run-time, do not specify the DECLARE_REGISTRY_RESOURCE or DECLARE_REGISTRY_RESOURCEID macro. Instead, create an array of _ATL_REGMAP_ENTRIES structures, where each entry contains a variable placeholder paired with a value to replace the placeholder at run time. Then call CComModule::UpdateRegistryFromResourceD or CComModule::UpdateRegistryFromResourceS, passing the array. This adds all the replacement values in the _ATL_REGMAP_ENTRIES structures to the Registrar’s replacement map.

For more information about replaceable parameters and scripting, see the article The ATL Registry Component (Registrar).

ATL Macros and Global Functions

See Also DECLARE_REGISTRY


DECLARE_REGISTRY_RESOURCEID

DECLARE_REGISTRY_RESOURCEID( x )

Parameters

x [in] Wizard-generated identifier of your resource.

Remarks

Same as DECLARE_REGISTRY_RESOURCE except that it uses a Wizard-generated UINT to identify the resource, rather than a string name.

When you create an object or control with the ATL Object Wizard, the wizard automatically implements script-based registry support and adds the DECLARE_REGISTRY_RESOURCEID macro to your files.

You can statically link to the ATL Registry Component (Registrar) for optimized registry access. To statically link to the Registrar code, add #define _ATL_STATIC_REGISTRY to your stdafx.h.

If you want ATL to substitute replacement values at run-time, do not specify the DECLARE_REGISTRY_RESOURCE or DECLARE_REGISTRY_RESOURCEID macro. Instead, create an array of _ATL_REGMAP_ENTRIES structures, where each entry contains a variable placeholder paired with a value to replace the placeholder at run time. Then call CComModule::UpdateRegistryFromResourceD or CComModule::UpdateRegistryFromResourceS, passing the array. This adds all the replacement values in the _ATL_REGMAP_ENTRIES structures to the Registrar’s replacement map.

For more information about replaceable parameters and scripting, see the article The ATL Registry Component (Registrar).

ATL Macros and Global Functions

See Also DECLARE_REGISTRY


DECLARE_WND_CLASS

DECLARE_WND_CLASS( WndClassName )

Parameters

WndClassName [in] The name of the new window class. If NULL, ATL will generate a window class name.

Remarks

Allows you to specify the name of a new window class, whose information will be managed by CWndClassInfo. DECLARE_WND_CLASS defines the new window class by implementing the following static function:

static CWndClassInfo& GetWndClassInfo();

CWindowImpl uses the DECLARE_WND_CLASS macro to create a window based on a new window class. To override this behavior, use the DECLARE_WND_SUPERCLASS macro or provide your own implementation of the GetWndClassInfo function.

For more information about using windows in ATL, see the article ATL Window Classes.

ATL Macros and Global Functions


DECLARE_WND_SUPERCLASS

DECLARE_WND_SUPERCLASS( WndClassName, OrigWndClassName )

Parameters

WndClassName [in] The name of the window class that will superclass OrigWndClassName. If NULL, ATL will generate a window class name.

OrigWndClassName [in] The name of an existing window class.

Remarks

Allows you to specify the name of a window class that will superclass an existing window class. CWndClassInfo manages the information of the superclass.

DECLARE_WND_SUPERCLASS implements the following static function:

static CWndClassInfo& GetWndClassInfo();

By default, CWindowImpl uses the DECLARE_WND_CLASS macro to create a window based on a new window class. By specifying the DECLARE_WND_SUPERCLASS macro in a CWindowImpl-derived class, the window class will be based on an existing class but will use your window procedure. This technique is called superclassing.

Besides using the DECLARE_WND_CLASS and DECLARE_WND_SUPERCLASS macros, you can override the GetWndClassInfo function with your own implementation.

For more information about superclassing, see "Window Procedure Superclassing" in the Win32 SDK. For more information about using windows in ATL, see the article ATL Window Classes.

ATL Macros and Global Functions


END_COM_MAP

END_COM_MAP( )

Remarks

Ends the definition of your COM interface map.

ATL Macros and Global Functions

See Also BEGIN_COM_MAP, COM_INTERFACE_ENTRY


END_CONNECTION_POINT_MAP

END_CONNECTION_POINT_MAP( )

Remarks

Marks the end of the connection point map entries. Start your connection point map with the BEGIN_CONNECTION_POINT_MAP macro, add entries for each of your connection points with the CONNECTION_POINT_ENTRY macro, and complete the map with the END_CONNECTION_POINT_MAP macro.

For example:

BEGIN_CONNECTION_POINT_MAP(CMyCPClass) 
   CONNECTION_POINT_ENTRY(m_cpInterfaceBeingExposed) 
END_CONNECTION_POINT_MAP( ) 

For more information about connection points in ATL, see the article Connection Points.

ATL Macros and Global Functions


END_MSG_MAP

END_MSG_MAP( )

Remarks

Marks the end of a message map. Always use the BEGIN_MSG_MAP macro to mark the beginning of a message map. Use ALT_MSG_MAP to declare subsequent alternate message maps. The following example shows the default message map and one alternate message map, each containing one handler function:

BEGIN_MSG_MAP(CMyClass) 
   MESSAGE_HANDLER(WM_PAINT, OnPaint) 
ALT_MSG_MAP(1) 
   MESSAGE_HANDLER(WM_SETFOCUS, OnSetFocus) 
END_MSG_MAP 

The next example shows two alternate message maps. The default message map is empty.

BEGIN_MSG_MAP(CMyClass) 
ALT_MSG_MAP(1) 
   MESSAGE_HANDLER(WM_PAINT, OnPaint) 
   MESSAGE_HANDLER(WM_SETFOCUS, OnSetFocus) 
ALT_MSG_MAP(2) 
   MESSAGE_HANDLER(WM_CREATE, OnCreate) 
END_MSG_MAP 

Note that there is always exactly one instance of BEGIN_MSG_MAP and END_MSG_MAP.

For more information about using message maps in ATL, see Message Maps in the article “ATL Window Classes.”

ATL Macros and Global Functions


END_OBJECT_MAP

END_OBJECT_MAP( )

Remarks

Marks the end of the map of ATL objects. When CComModule::RegisterServer is called, it updates the system registry for each object in the object map.

Start your object map with the BEGIN_OBJECT_MAP macro, add entries for each object with the OBJECT_ENTRY macro, and complete the map with the END_OBJECT_MAP macro.

ATL Macros and Global Functions

See Also BEGIN_OBJECT_MAP, OBJECT_ENTRY


END_PROPERTY_MAP

END_PROPERTY_MAP( )

Remarks

Marks the end of the object’s property map. When you create a control with the ATL Object Wizard, the wizard will create an empty property map by specifying BEGIN_PROPERTY_MAP followed by END_PROPERTY_MAP.

Example

See BEGIN_PROPERTY_MAP.

ATL Macros and Global Functions

See Also PROP_ENTRY, PROP_ENTRY_EX, PROP_PAGE


IMPLEMENT_BSTR_STOCKPROP

IMPLEMENT_BSTR_STOCKPROP( fname, pname, dispid )

Parameters

fname [in] Name used to create the names of the put and get methods.

pname [in] Name used to create the name of the data member that stores the property value.

dispid [in] The DISPID of the property.

Remarks

Implements text stock properties. Allocates a BSTR data member in your control class and copies pname into the data member. Creates a put and get method for the property, and adds code to notify and synchronize with the container if the property changes.

The put and get method names are created by appending fname to put_ and get_. For example, if fname is Caption, the method names are put_Caption and get_Caption.

The data member name is created by appending pname to m_. For example, if pname is bstrCaption, the data member is m_bstrCaption.

ATL Macros and Global Functions

See Also CStockPropImpl, IMPLEMENT_STOCKPROP, CComControl::m_bstrCaption, CComControl::m_bstrText


IMPLEMENT_SMARTPTR_STOCKPROP

IMPLEMENT_SMARTPTR_STOCKPROP( type, fname, pname, dispid )

Parameters

type [in] The data type of the property.

fname [in] Name used to create the names of the put and get methods.

pname [in] Name used to create the name of the data member that stores the property value.

dispid [in] The DISPID of the property.

Remarks

Implements stock properties that are interface pointers. Same as the IMPLEMENT_STOCKPROP macro except that an AddRef is performed on the stock property pointer before the pointer is passed back to the caller. Standard stock properties that are interface pointers are Font, Mouse Icon, and Picture.

Creates a data member in your control class for a property, creates a put and get method for the property, and adds code to notify and synchronize with the container if the property changes.

The put and get method names are created by appending fname to put_ and get_. For example, if fname is Font, the method names are put_Font and get_Font.

The data member name is created by appending pname to m_. For example, if pname is pFont, the data member is m_pFont.

ATL Macros and Global Functions

See Also CStockPropImpl, IMPLEMENT_BSTR_STOCKPROP, CComControl::m_pFont, CComControl::m_pMouseIcon, CComControl::m_pPicture


IMPLEMENT_STOCKPROP

IMPLEMENT_STOCKPROP( type, fname, pname, dispid )

Parameters

type [in] The data type of the property.

fname [in] Name used to create the names put and get methods.

pname [in] Name used to create the name of the data member that stores the property value.

dispid [in] The DISPID of the property..

Remarks

Creates a data member in your control class for a property, creates put and get methods for the property, and adds code to notify and synchronize with the container if property changes.

The put and get method names are created by appending fname to put_ and get_. For example, if fname is AutoSize, the method names are put_AutoSize and get_AutoSize.

The data member name is created by appending pname to m_. If pname is bAutoSize, the data member is m_bAutoSize.

ATL Macros and Global Functions

See Also CStockPropImpl, CComControl, IMPLEMENT_BSTR_STOCKPROP


MESSAGE_HANDLER

MESSAGE_HANDLER( msg, func )

Parameters

msg [in] The Windows message.

func [in] The name of the message-handler function.

Remarks

Defines an entry in a message map. MESSAGE_HANDLER maps a Windows message to the specified handler function. For example:

class CMyClass : ... 
{ 
public: 
   ... 
   BEGIN_MSG_MAP(CMyClass) 
      MESSAGE_HANDLER(WM_PAINT, OnPaint) 
      ... 
   END_MSG_MAP() 
   // When a CMyClass object receives a WM_PAINT 
   // message, the message is directed to 
   // CMyClass::OnPaint for the actual processing. 
   LRESULT OnPaint( ... ) 
   { ... } 
}; 

Any function specified in a MESSAGE_HANDLER macro must defined as follows:

LRESULT MessageHandler(UINT uMsg, WPARAM wParam, LPARAM lParam, BOOL& bHandled);

The message map sets bHandled to TRUE before MessageHandler is called. If MessageHandler does not fully handle the message, it should set bHandled to FALSE to indicate the message needs further processing.

Note Always begin a message map with BEGIN_MSG_MAP. You can then declare subsequent alternate message maps with ALT_MSG_MAP. The END_MSG_MAP macro marks the end of the message map. Every message map must have exactly one instance of BEGIN_MSG_MAP and END_MSG_MAP.

In addition to MESSAGE_HANDLER, you can use COMMAND_HANDLER and NOTIFY_HANDLER to map WM_COMMAND and WM_NOTIFY messages, respectively.

For more information about using message maps in ATL, see Message Maps in the article “ATL Window Classes.”

ATL Macros and Global Functions

See Also MESSAGE_RANGE_HANDLER


MESSAGE_RANGE_HANDLER

MESSAGE_RANGE_HANDLER( msgFirst, msgLast, func )

Parameters

msgFirst [in] Marks the beginning of a contiguous range of messages.

msgLast [in] Marks the end of a contiguous range of messages.

func [in] The name of the message-handler function.

Remarks

Similar to MESSAGE_HANDLER, but maps a range of Windows messages to a single handler function.

ATL Macros and Global Functions

See Also COMMAND_RANGE_HANDLER, NOTIFY_RANGE_HANDLER


NOTIFY_CODE_HANDLER

NOTIFY_CODE_HANDLER( cd, func )

Parameters

cd [in] The notification code.

func [in] The name of the message-handler function.

Remarks

Similar to NOTIFY_HANDLER, but maps a WM_NOTIFY message based only on the notification code.

ATL Macros and Global Functions

See Also NOTIFY_ID_HANDLER, NOTIFY_RANGE_HANDLER, COMMAND_CODE_HANDLER, MESSAGE_HANDLER


NOTIFY_HANDLER

NOTIFY_HANDLER( id, cd, func )

Parameters

id [in] The identifier of the control sending the message.

code [in] The notification code.

func [in] The name of the message-handler function.

Remarks

Defines an entry in a message map. NOTIFY_HANDLER maps a WM_NOTIFY message to the specified handler function, based on the notification code and the control identifier. For example:

class CMyClass : ... 
{ 
public: 
   ... 
   BEGIN_MSG_MAP(CMyClass) 
      NOTIFY_HANDLER(IDC_MYCTL, NM_CLICK, OnClick) 
      ... 
   END_MSG_MAP() 
   // When a CMyClass object receives a WM_NOTIFY 
   // message identified by IDC_MYCTL and NM_CLICK, 
   // the message is directed to CMyClass::OnClick 
   // for the actual processing. 
   LRESULT OnClick( ... ) 
   { ... } 
}; 

Any function specified in a NOTIFY_HANDLER macro must defined as follows:

LRESULT NotifyHandler(int idCtrl, LPNMHDR pnmh, BOOL& bHandled);

The message map sets bHandled to TRUE before NotifyHandler is called. If NotifyHandler does not fully handle the message, it should set bHandled to FALSE to indicate the message needs further processing.

Note Always begin a message map with BEGIN_MSG_MAP. You can then declare subsequent alternate message maps with ALT_MSG_MAP. The END_MSG_MAP macro marks the end of the message map. Every message map must have exactly one instance of BEGIN_MSG_MAP and END_MSG_MAP.

In addition to NOTIFY_HANDLER, you can use MESSAGE_HANDLER to map a WM_NOTIFY message without regard to an identifier or code. In this case, MESSAGE_HANDLER(WM_NOTIFY, OnHandlerFunction) will direct all WM_NOTIFY messages to OnHandlerFunction.

For more information about using message maps in ATL, see Message Maps in the article “ATL Window Classes.”

ATL Macros and Global Functions

See Also NOTIFY_ID_HANDLER, NOTIFY_CODE_HANDLER, NOTIFY_RANGE_HANDLER, COMMAND_HANDLER


NOTIFY_ID_HANDLER

NOTIFY_ID_HANDLER( id, func )

Parameters

id [in] The identifier of the control sending the message.

func [in] The name of the message-handler function.

Remarks

Similar to NOTIFY_HANDLER, but maps a WM_NOTIFY message based only on the control identifier.

ATL Macros and Global Functions

See Also NOTIFY_CODE_HANDLER, NOTIFY_RANGE_HANDLER, COMMAND_ID_HANDLER, MESSAGE_HANDLER


NOTIFY_RANGE_HANDLER

NOTIFY_RANGE_HANDLER( idFirst, idLast, func )

Parameters

idFirst [in] Marks the beginning of a contiguous range of WM_NOTIFY messages.

idLast [in] Marks the end of a contiguous range of WM_NOTIFY messages.

func [in] The name of the message-handler function.

Remarks

Similar to NOTIFY_HANDLER, but maps a range of WM_NOTIFY messages to a single handler function. This range is based on the identifier of the control sending the message.

ATL Macros and Global Functions

See Also NOTIFY_ID_HANDLER, NOTIFY_CODE_HANDLER, COMMAND_RANGE_HANDLER, MESSAGE_RANGE_HANDLER


OBJECT_ENTRY

OBJECT_ENTRY( clsid, class )

Parameters

clsid [in] The CLSID of the ATL object to be entered into the object map.

class [in] The name of the class of the ATL object.

Remarks

Enters the function pointers of the creator class and class factory creator class CreateInstance functions for this object into the ATL object map. When CComModule::RegisterServer is called, it updates the system registry for each object in the object map.

Start your object map with the BEGIN_OBJECT_MAP macro, add entries for each object with the OBJECT_ENTRY macro, and complete the map with the END_OBJECT_MAP macro.

See Also DECLARE_OBJECT_DESCRIPTION

ATL Macros and Global Functions


PROP_ENTRY

PROP_ENTRY( szDesc, dispid, clsid )

Parameters

szDesc [in] The property description.

dispid [in] The property’s DISPID.

clsid [in] The CLSID of the associated property page.

Remarks

Use this macro to enter a property description, property DISPID, and property page CLSID into the object’s property map. The BEGIN_PROPERTY_MAP macro marks the beginning of the property map; the END_PROPERTY_MAP macro marks the end.

Example

See BEGIN_PROPERTY_MAP.

ATL Macros and Global Functions

See Also PROP_ENTRY_EX, PROP_PAGE


PROP_ENTRY_EX

PROP_ENTRY_EX( szDesc, dispid, clsid, iidDispatch )

Parameters

szDesc [in] The property description.

dispid [in] The property’s DISPID.

clsid [in] The CLSID of the associated property page.

iidDispatch [in] The IID of the dual interface defining the property.

Remarks

Similar to PROP_ENTRY, but allows you specify a particular IID if your object supports multiple dual interfaces.

The BEGIN_PROPERTY_MAP macro marks the beginning of the property map; the END_PROPERTY_MAP macro marks the end.

Example

The following example groups entries for IMyDual1 followed by an entry for IMyDual2. Grouping by dual interface will improve performance.

BEGIN_PROPERTY_MAP( CMyClass )
   PROP_ENTRY_EX( "Caption", DISPID_CAPTION, 
                  CLSID_CMyProps, IID_IMyDual1 )
   PROP_ENTRY_EX( "Enabled", DISPID_ENABLED, 
                  CLSID_CMyProps, IID_IMyDual1 )
   PROP_ENTRY_EX( "Width", DISPIS_WIDTH,
                  CLSID_CMyProps, IID_IMyDual2 )
END_PROPERTY_MAP( )

ATL Macros and Global Functions

See Also PROP_PAGE


PROP_PAGE

PROP_PAGE( clsid )

Parameters

clsid [in] The CLSID of a property page.

Remarks

Use this macro to enter a property page CLSID into the object’s property map. PROP_PAGE is similar to PROP_ENTRY, but does not require a property description or DISPID.

Note If you have already entered a CLSID with PROP_ENTRY or PROP_ENTRY_EX, you do not need to make an additional entry with PROP_PAGE.

The BEGIN_PROPERTY_MAP macro marks the beginning of the property map; the END_PROPERTY_MAP macro marks the end.

Example

BEGIN_PROPERTY_MAP( CMyClass )
   PROP_PAGE( CLSID_CMyClassPropPage1 )
   PROP_PAGE( CLSID_CMyClassPropPage2 )
END_PROPERTY_MAP( )

ATL Macros and Global Functions


String Conversion Macros

The syntax of the ATL string conversion macros is:
MACRONAME(string_address)

For example:
A2W(lpa)

In the macro names, the source string type is on the left (for example, A) and the destination string type on the right (for example, W). A stands for LPSTR, OLE stands for LPOLESTR, T stands for LPTSTR, and W stands for LPWSTR.

Thus, A2W converts an LPSTR to an LPWSTR, OLE2T converts an LPOLESTR to an LPTSTR, and so on.

The destination string is created using _alloca, except when the destination type is BSTR. Using _alloca allocates memory off the stack, so that when your function returns, it is automatically cleaned up.

If there is a C in the macro name, the macro converts to a const string. For example, W2CA converts an LPWSTR to an LPCSTR.

Note When using an ATL string conversion macro, specify the USES_CONVERSION macro at the beginning of your function in order to avoid compiler errors. For example:

void func( LPSTR lpsz )
{
   USES_CONVERSION;
   ...
   LPWSTR x = A2W(lpsz)
   // Do something with x
   ...
}

The behavior of the ATL string conversion macros depends on the compiler directive in effect, if any. If the source and destination types are the same, no conversion takes place. Compiler directives change T and OLE as follows.

Compiler directive in effectT becomesOLE becomes
noneAW
_UNICODEWW
OLE2ANSIAA
_UNICODE and OLEANSIWA

The following table lists the ATL string conversion macros.

ATL String Conversion Macros
A2BSTROLE2AT2AW2A
A2COLEOLE2BSTRT2BSTRW2BSTR
A2CTOLE2CAT2CAW2CA
A2CWOLE2CTT2COLEW2COLE
A2OLEOLE2CWT2CWW2CT
A2TOLE2TT2OLEW2OLE
A2WOLE2WT2WW2T

ATL Macros and Global Functions


DEVMODE and TEXTMETRIC String Conversion Macros

These macros create a copy of a DEVMODE or TEXTMETRIC structure and convert the strings within the new structure to a new string type. The macros allocate memory on the stack for the new structure and return a pointer to the new structure.

The syntax is:
MACRONAME(address_of_existing_structure)

For example:
DEVMODEA2W(lpa)
and
TEXTEMTRICA2W(lptma)

In the macro names, the string type in the source structure is on the left (for example, A) and the string type in the destination structure is on the right (for example, W). A stands for LPSTR, OLE stands for LPOLESTR, T stands for LPTSTR, and W stands for LPWSTR.

Thus, DEVMODEA2W copies a DEVMODE structure with LPSTR strings into a DEVMODE structure with LPWSTR strings, TEXTMETRICOLE2T copies a TEXTMETRIC structure with LPOLESTR strings into a TEXTMETRIC structure with LPTSTR strings, and so on.

The two strings converted in the DEVMODE structure are the device name (dmDeviceName) and the form name (dmFormName). The DEVMODE string conversion macros also update the structure size (dmSize).

The four strings converted in the TEXTMETRIC structure are the first character (tmFirstChar), the last character (tmLastChar), the default character (tmDefaultChar), and the break character (tmBreakChar).

The behavior of the DEVMODE and TEXTMETRIC string conversion macros depends on the compiler directive in effect, if any. If the source and destination types are the same, no conversion takes place. Compiler directives change T and OLE as follows.

Compiler directive in effectT becomesOLE becomes
noneAW
_UNICODEWW
OLE2ANSIAA
_UNICODE and OLEANSIWA

The following table lists the DEVMODE and TEXTMETRIC string conversion macros.

DEVMODE and TEXTMETRIC String Conversion Macros
DEVMODEA2WTEXTMETRICA2W
DEVMODEOLE2TTEXTMETRICOLE2T
DEVMODET2OLETEXTMETRICT2OLE
DEVMODEW2ATEXTMETRICW2A

ATL Macros and Global Functions