Category Macros
The latest version of this topic can be found at Category Macros.
These macros define category maps.
| BEGIN_CATEGORY_MAP | Marks the beginning of the category map. |
| END_CATEGORY_MAP | Marks the end of the category map. |
| IMPLEMENTED_CATEGORY | Indicates categories that are implemented by the COM object. |
| REQUIRED_CATEGORY | Indicates categories that are required of the container by the COM object. |
BEGIN_CATEGORY_MAP
Marks the beginning of the category map.
BEGIN_CATEGORY_MAP
(theClass)
Parameters
theClass
[in] The name of the class containing the category map.
Remarks
The category map is used to specify which component categories the COM class will implement and which categories it requires from its container.
Add an IMPLEMENTED_CATEGORY entry to the map for each category implemented by the COM class. Add a REQUIRED_CATEGORY entry to the map for each category that the class requires its clients to implement. Mark the end of the map with the END_CATEGORY_MAP macro.
The component categories listed in the map will be registered automatically when the module is registered if the class has an associated OBJECT_ENTRY_AUTO or OBJECT_ENTRY_NON_CREATEABLE_EX_AUTO.
Note
ATL uses the standard component categories manager to register component categories. If the manager is not present on the system when the module is registered, registration succeeds, but the component categories will not be registered for that class.
For more information about component categories, see What are Component Categories and how do they work in the Windows SDK.
Example
BEGIN_CATEGORY_MAP(CMyCtrl)
IMPLEMENTED_CATEGORY(CATID_Insertable)
END_CATEGORY_MAP()
END_CATEGORY_MAP
Marks the end of the category map.
END_CATEGORY_MAP
()
Example
See the example for BEGIN_CATEGORY_MAP.
IMPLEMENTED_CATEGORY
Add an IMPLEMENTED_CATEGORY macro to your component's category map to specify that it should be registered as implementing the category identified by the catID parameter.
IMPLEMENTED_CATEGORY
(catID)
Parameters
catID
[in] A CATID constant or variable holding the globally unique identifier (GUID) for the implemented category. The address of catID will be taken and added to the map. See the table below for a selection of stock categories.
Remarks
The component categories listed in the map will be registered automatically when the module is registered if the class has an associated OBJECT_ENTRY_AUTO or OBJECT_ENTRY_NON_CREATEABLE_EX_AUTO macro.
Clients can use the category information registered for the class to determine its capabilities and requirements without having to create an instance of it.
For more information about component categories, see What are Component Categories and how do they work in the Windows SDK.
A Selection of Stock Categories
| Description | Symbol | Registry GUID |
|---|---|---|
| Safe For Scripting | CATID_SafeForScripting | {7DD95801-9882-11CF-9FA9-00AA006C42C4} |
| Safe For Initialization | CATID_SafeForInitializing | {7DD95802-9882-11CF-9FA9-00AA006C42C4} |
| Simple Frame Site Containment | CATID_SimpleFrameControl | {157083E0-2368-11cf-87B9-00AA006C8166} |
| Simple Data Binding | CATID_PropertyNotifyControl | {157083E1-2368-11cf-87B9-00AA006C8166} |
| Advanced Data Binding | CATID_VBDataBound | {157083E2-2368-11cf-87B9-00AA006C8166} |
| Windowless Controls | CATID_WindowlessObject | {1D06B600-3AE3-11cf-87B9-00AA006C8166} |
| Internet-Aware Objects | See Internet Aware Objects in the Windows SDK for a sample list. | Â |
Example
BEGIN_CATEGORY_MAP(CMyCtrl)
IMPLEMENTED_CATEGORY(CATID_Insertable)
END_CATEGORY_MAP()
REQUIRED_CATEGORY
Add a REQUIRED_CATEGORY macro to your component's category map to specify that it should be registered as requiring the category identified by the catID parameter.
REQUIRED_CATEGORY(Â
catID Â)
Parameters
catID
[in] A CATID constant or variable holding the globally unique identifier (GUID) for the required category. The address of catID will be taken and added to the map. See the table below for a selection of stock categories.
Remarks
The component categories listed in the map will be registered automatically when the module is registered if the class has an associated OBJECT_ENTRY_AUTO or OBJECT_ENTRY_NON_CREATEABLE_EX_AUTO macro.
Clients can use the category information registered for the class to determine its capabilities and requirements without having to create an instance of it. For example, a control may require that a container support data binding. The container can find out if it has the capabilities necessary to host the control by querying the category manager for the categories required by that control. If the container does not support a required feature, it can refuse to host the COM object.
For more information about component categories, including a sample list, see What are Component Categories and how do they work in the Windows SDK.
A Selection of Stock Categories
| Description | Symbol | Registry GUID |
|---|---|---|
| Safe For Scripting | CATID_SafeForScripting | {7DD95801-9882-11CF-9FA9-00AA006C42C4} |
| Safe For Initialization | CATID_SafeForInitializing | {7DD95802-9882-11CF-9FA9-00AA006C42C4} |
| Simple Frame Site Containment | CATID_SimpleFrameControl | {157083E0-2368-11cf-87B9-00AA006C8166} |
| Simple Data Binding | CATID_PropertyNotifyControl | {157083E1-2368-11cf-87B9-00AA006C8166} |
| Advanced Data Binding | CATID_VBDataBound | {157083E2-2368-11cf-87B9-00AA006C8166} |
| Windowless Controls | CATID_WindowlessObject | {1D06B600-3AE3-11cf-87B9-00AA006C8166} |
| Internet-Aware Objects | See Internet Aware Objects in the Windows SDK for a sample list. | Â |
Example
BEGIN_CATEGORY_MAP(CMyWindow)
REQUIRED_CATEGORY(CATID_InternetAware)
END_CATEGORY_MAP()