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_AGGREGATABLE | Declares that your object can be aggregated (the default). |
DECLARE_CLASSFACTORY | Declares the class factory to be CComClassFactory, the ATL default class factory. |
DECLARE_CLASSFACTORY_EX | Declares your class factory object to be the class factory. |
DECLARE_CLASSFACTORY2 | Declares CComClassFactory2 to be the class factory. |
DECLARE_CLASSFACTORY_AUTO_THREAD | Declares CComClassFactoryAutoThread to be the class factory. |
DECLARE_CLASSFACTORY_SINGLETON | Declares CComClassFactorySingleton to be the class factory. |
DECLARE_GET_CONTROLLING_UNKNOWN | Declares a virtual GetControllingUnknown function. |
DECLARE_NOT_AGGREGATABLE | Declares that your object cannot be aggregated. |
DECLARE_ONLY_AGGREGATABLE | Declares that your object must be aggregated. |
DECLARE_POLY_AGGREGATABLE | Checks the value of the outer unknown and declares your object aggregatable or not aggregatable, as appropriate. |
DECLARE_PROTECT_FINAL_CONSTRUCT | Protects the outer object from deletion during construction of an inner object. |
COM Map Macros and Global Functions | |
AtlInternalQueryInterface | Delegates to the IUnknown of a nonaggregated object. |
BEGIN_COM_MAP | Marks the beginning of the COM interface map entries. |
COM_INTERFACE_ENTRY and its variations | Enters interfaces into the COM interface map. |
END_COM_MAP | Marks the end of the COM interface map entries. |
Connection Point Macros and Global Functions | |
AtlAdvise | Creates a connection between an object's connection point and a client's sink. |
AtlUnadvise | Terminates the connection established through AtlAdvise. |
BEGIN_CONNECTION_POINT_MAP | Marks the beginning of the connection point map entries. |
CONNECTION_POINT_ENTRY | Enters connection points into the map. |
END_CONNECTION_POINT_MAP | Marks the end of the connection point map entries. |
Debugging and Error Reporting Macros and Global Functions | |
AtlReportError | Sets up IErrorInfo to provide error details to a client. |
AtlTrace | Global function that sends a formatted message and/or variable values to the dump device. |
ATLTRACE | Sends a formatted message and/or variable values to the dump device. |
ATLTRACENOTIMPL | Sends a message to the dump device that the specified function is not implemented. |
Device Context Global Functions | |
AtlCreateTargetDC | Creates a device context. |
Event Handling Global Functions | |
AtlWaitWithMessageLoop | Waits for an object to be signalled, meanwhile dispatching window messages if necessary. |
Marshaling Global Functions | |
AtlFreeMarshalStream | Releases the marshal data and the IStream pointer. |
AtlMarshalPtrInProc | Creates a new stream object and marshals the specified interface pointer. |
AtlUnmarshalPtr | Converts a stream's marshaling data into an interface pointer. |
Message Map Macros | |
BEGIN_MSG_MAP | Marks the beginning of the default message map. |
ALT_MSG_MAP | Marks the beginning of an alternate message map. |
MESSAGE_HANDLER | Maps a Windows message to a handler function. |
MESSAGE_RANGE_HANDLER | Maps a contiguous range of Windows messages to a handler function. |
COMMAND_HANDLER | Maps 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_HANDLER | Maps a WM_COMMAND message to a handler function, based on the identifier of the menu item, control, or accelerator. |
COMMAND_CODE_HANDLER | Maps a WM_COMMAND message to a handler function, based on the notification code. |
COMMAND_RANGE_HANDLER | Maps a contiguous range of WM_COMMAND messages to a handler function. |
NOTIFY_HANDLER | Maps a WM_NOTIFY message to a handler function, based on the notification code and the control identifier. |
NOTIFY_ID_HANDLER | Maps a WM_NOTIFY message to a handler function, based on the control identifier. |
NOTIFY_CODE_HANDLER | Maps a WM_NOTIFY message to a handler function, based on the notification code. |
NOTIFY_RANGE_HANDLER | Maps a contiguous range of WM_NOTIFY messages to a handler function. |
CHAIN_MSG_MAP | Chains to the default message map in the base class. |
CHAIN_MSG_MAP_MEMBER | Chains to the default message map in a data member of the class. |
CHAIN_MSG_MAP_ALT | Chains to an alternate message map in the base class. |
CHAIN_MSG_MAP_ALT_MEMBER | Chains to an alternate message map in a data member of the class. |
CHAIN_MSG_MAP_DYNAMIC | Chains to the message map in another class at run time. |
CHAIN_MSG_MAP_ALT_DYNAMIC | Chains to an alternate message map in another class at run time. |
END_MSG_MAP | Marks the end of a message map. |
Object Map Macros | |
BEGIN_OBJECT_MAP | Marks the beginning of the ATL object map and initializes the array of object descriptions. |
OBJECT_ENTRY | Enters an ATL object into the object map, updates the registry, and creates an instance of the object. |
END_OBJECT_MAP | Marks the end of the ATL object map. |
DECLARE_OBJECT_DESCRIPTION | Allows you to specify a class objects text description, which will be entered into the object map. |
Pixel/HIMETRIC Conversion Global Functions | |
AtlHiMetricToPixel | Converts HIMETRIC units (each unit is 0.01 millimeter) to pixels. |
AtlPixelToHiMetric | Converts pixels to HIMETRIC units (each unit is 0.01 millimeter). |
Property Map Macros | |
BEGIN_PROPERTY_MAP | Marks the beginning of the ATL property map. |
PROP_ENTRY | Enters a property description, property DISPID, and property page CLSID into the property map. |
PROP_ENTRY_EX | Enters a property description, property DISPID, property page CLSID, and IDispatch IID into the property map. |
PROP_PAGE | Enters a property page CLSID into the property map. |
END_PROPERTY_MAP | Marks the end of the ATL property map. |
Registry Macros | |
DECLARE_NO_REGISTRY | Avoids default ATL registration. |
DECLARE_REGISTRY | Enters or removes the main object's entry in the system registry. |
DECLARE_REGISTRY_RESOURCE | Finds the named resource and runs the registry script within it. |
DECLARE_REGISTRY_RESOURCEID | Finds the resource identified by an ID number and runs the registry script within it. |
Stock Property Macros | |
IMPLEMENT_BSTR_STOCKPROP | Implements a text stock property for an ATL object. |
IMPLEMENT_SMARTPTR_STOCKPROP | Implements a stock property that is an interface pointer. |
IMPLEMENT_STOCKPROP | Implements a stock property. |
String Conversion Macros | |
String Conversion Macros | Set of macros that convert between string types. |
DEVMODE and TEXTMETRIC String Conversion Macros | Set of macros that convert the strings within DEVMODE and TEXTMETRIC structures. |
Window Class Macros | |
DECLARE_WND_CLASS | Allows you to specify the name of a new window class. |
DECLARE_WND_SUPERCLASS | Allows you to specify the name of an existing window class on which a new window class will be based. |
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
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
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
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
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
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
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
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
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
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( 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( 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
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
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
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( 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( 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( 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.
Macro | Description |
MESSAGE_HANDLER | Maps a Windows message to a handler function. |
MESSAGE_RANGE_HANDLER | Maps a contiguous range of Windows messages to a handler function. |
COMMAND_HANDLER | Maps 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_HANDLER | Maps a WM_COMMAND message to a handler function, based on the identifier of the menu item, control, or accelerator. |
COMMAND_CODE_HANDLER | Maps a WM_COMMAND message to a handler function, based on the notification code. |
COMMAND_RANGE_HANDLER | Maps a contiguous range of WM_COMMAND messages to a handler function, based on the identifier of the menu item, control, or accelerator. |
NOTIFY_HANDLER | Maps a WM_NOTIFY message to a handler function, based on the notification code and the control identifier. |
NOTIFY_ID_HANDLER | Maps a WM_NOTIFY message to a handler function, based on the control identifier. |
NOTIFY_CODE_HANDLER | Maps a WM_NOTIFY message to a handler function, based on the notification code. |
NOTIFY_RANGE_HANDLER | Maps 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.
Macro | Description |
CHAIN_MSG_MAP | Chains to the default message map in the base class. |
CHAIN_MSG_MAP_MEMBER | Chains to the default message map in a data member of the class. |
CHAIN_MSG_MAP_ALT | Chains to an alternate message map in the base class. |
CHAIN_MSG_MAP_ALT_MEMBER | Chains to an alternate message map in a data member of the class. |
CHAIN_MSG_MAP_DYNAMIC | Chains to the default message map in another class at run time. |
CHAIN_MSG_MAP_ALT_DYNAMIC | Chains 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( 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( theClass )
Parameters
theClass [in] The name of the class containing the property map.
Remarks
Marks the beginning of the objects 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( 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( 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( 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( 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( 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( 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
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:
ATL Macros and Global Functions
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
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
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
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
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
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
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( 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
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
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
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
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
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
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
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( 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
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( 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( 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( 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( 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( 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( 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( )
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( 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 objects 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_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 objects class definition, you override this default.
ATL Macros and Global Functions
See Also DECLARE_CLASSFACTORY_EX, DECLARE_CLASSFACTORY2, DECLARE_CLASSFACTORY_SINGLETON
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 objects 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( 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 objects 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( )
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( )
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( 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( x )
Parameters
x [in] The class objects 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( 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( 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( )
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( 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( 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 Registrars 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( 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 Registrars 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( 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( 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( )
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( )
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( )
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( )
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( )
Remarks
Marks the end of the objects 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( 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( 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( 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( 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( 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( 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( 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( 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( 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( 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( szDesc, dispid, clsid )
Parameters
szDesc [in] The property description.
dispid [in] The propertys 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 objects 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( szDesc, dispid, clsid, iidDispatch )
Parameters
szDesc [in] The property description.
dispid [in] The propertys 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( clsid )
Parameters
clsid [in] The CLSID of a property page.
Remarks
Use this macro to enter a property page CLSID into the objects 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
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 effect | T becomes | OLE becomes |
none | A | W |
_UNICODE | W | W |
OLE2ANSI | A | A |
_UNICODE and OLEANSI | W | A |
The following table lists the ATL string conversion macros.
ATL String Conversion Macros | |||
A2BSTR | OLE2A | T2A | W2A |
A2COLE | OLE2BSTR | T2BSTR | W2BSTR |
A2CT | OLE2CA | T2CA | W2CA |
A2CW | OLE2CT | T2COLE | W2COLE |
A2OLE | OLE2CW | T2CW | W2CT |
A2T | OLE2T | T2OLE | W2OLE |
A2W | OLE2W | T2W | W2T |
ATL Macros and Global Functions
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 effect | T becomes | OLE becomes |
none | A | W |
_UNICODE | W | W |
OLE2ANSI | A | A |
_UNICODE and OLEANSI | W | A |
The following table lists the DEVMODE and TEXTMETRIC string conversion macros.
DEVMODE and TEXTMETRIC String Conversion Macros | |||
DEVMODEA2W | TEXTMETRICA2W | ||
DEVMODEOLE2T | TEXTMETRICOLE2T | ||
DEVMODET2OLE | TEXTMETRICT2OLE | ||
DEVMODEW2A | TEXTMETRICW2A |