| title | ms.custom | ms.date | ms.reviewer | ms.suite | ms.technology | ms.tgt_pltfrm | ms.topic | f1_keywords | dev_langs | helpviewer_keywords | ms.assetid | caps.latest.revision | author | ms.author | manager | ||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Run-Time Object Model Services | Microsoft Docs |
11/04/2016 |
|
article |
|
|
|
4a3e79df-2ee3-43a4-8193-20298828de85 |
15 |
mikeblome |
mblome |
ghogen |
The classes CObject and CRuntimeClass encapsulate several object services, including access to run-time class information, serialization, and dynamic object creation. All classes derived from CObject inherit this functionality.
Access to run-time class information enables you to determine information about an object's class at run time. The ability to determine the class of an object at run time is useful when you need extra type-checking of function arguments and when you must write special-purpose code based on the class of an object. Run-time class information is not supported directly by the C++ language.
Serialization is the process of writing or reading an object's contents to or from a file. You can use serialization to store an object's contents even after the application exits. The object can then be read from the file when the application is restarted. Such data objects are said to be "persistent."
Dynamic object creation enables you to create an object of a specified class at run time. For example, document, view, and frame objects must support dynamic creation because the framework needs to create them dynamically.
The following table lists the MFC macros that support run-time class information, serialization, and dynamic creation.
For more information on these run-time object services and serialization, see the article CObject Class: Accessing Run-Time Class Information.
| DECLARE_DYNAMIC | Enables access to run-time class information (must be used in the class declaration). |
| DECLARE_DYNCREATE | Enables dynamic creation and access to run-time class information (must be used in the class declaration). |
| DECLARE_SERIAL | Enables serialization and access to run-time class information (must be used in the class declaration). |
| IMPLEMENT_DYNAMIC | Enables access to run-time class information (must be used in the class implementation). |
| IMPLEMENT_DYNCREATE | Enables dynamic creation and access to run-time information (must be used in the class implementation). |
| IMPLEMENT_SERIAL | Permits serialization and access to run-time class information (must be used in the class implementation). |
| RUNTIME_CLASS | Returns the CRuntimeClass structure that corresponds to the named class. |
OLE frequently requires the dynamic creation of objects at run time. For example, an OLE server application must be able to create OLE items dynamically in response to a request from a client. Similarly, an automation server must be able to create items in response to requests from automation clients.
The Microsoft Foundation Class Library provides two macros specific to OLE.
| AFX_COMCTL32_IF_EXISTS | Determines whether the Common Controls library implements the specified API. |
| AFX_COMCTL32_IF_EXISTS2 | Determines whether the Common Controls library implements the specified API. |
| DECLARE_OLECREATE | Enables objects to be created through OLE automation. |
| DECLARE_OLECTLTYPE | Declares the GetUserTypeNameID and GetMiscStatus member functions of your control class. |
| DECLARE_PROPPAGEIDS | Declares that the OLE control provides a list of property pages to display its properties. |
| IMPLEMENT_OLECREATE | Enables objects to be created by the OLE system. |
| IMPLEMENT_OLECTLTYPE | Implements the GetUserTypeNameID and GetMiscStatus member functions of your control class. |
| IMPLEMENT_OLECREATE_FLAGS | Either this macro or IMPLEMENT_OLECREATE must appear in the implementation file for any class that uses DECLARE_OLECREATE. |
Determines whether the Common Controls library implements the specified API.
AFX_COMCTL32_IF_EXISTS( proc );
proc
Pointer to a null-terminated string containing the function name, or specifies the function's ordinal value. If this parameter is an ordinal value, it must be in the low-order word; the high-order word must be zero. This parameter must be in Unicode.
Use this macro to determine whether the Common Controls library the function specified by proc (instead of calling GetProcAddress.
afxcomctl32.h, afxcomctl32.inl
Isolation of the MFC Common Controls Library AFX_COMCTL32_IF_EXISTS2
Determines whether the Common Controls library implements the specified API (this is the Unicode version of AFX_COMCTL32_IF_EXISTS).
AFX_COMCTL32_IF_EXISTS2( proc );
proc
Pointer to a null-terminated string containing the function name, or specifies the function's ordinal value. If this parameter is an ordinal value, it must be in the low-order word; the high-order word must be zero. This parameter must be in Unicode.
Use this macro to determine whether the Common Controls library the function specified by proc (instead of calling GetProcAddress. This macro is the Unicode version of AFX_COMCTL32_IF_EXISTS.
afxcomctl32.h, afxcomctl32.inl
Isolation of the MFC Common Controls Library AFX_COMCTL32_IF_EXISTS
Adds the ability to access run-time information about an object's class when deriving a class from CObject.
DECLARE_DYNAMIC(class_name)
class_name
The actual name of the class.
Add the DECLARE_DYNAMIC macro to the header (.h) module for the class, then include that module in all .cpp modules that need access to objects of this class.
If you use the DECLARE_ DYNAMIC and IMPLEMENT_DYNAMIC macros as described, you can then use the RUNTIME_CLASS macro and the CObject::IsKindOf function to determine the class of your objects at run time.
If DECLARE_DYNAMIC is included in the class declaration, then IMPLEMENT_DYNAMIC must be included in the class implementation.
For more information on the DECLARE_DYNAMIC macro, see CObject Class Topics.
See the example for IMPLEMENT_DYNAMIC.
Header: afx.h
Enables objects of CObject-derived classes to be created dynamically at run time.
DECLARE_DYNCREATE(class_name)
class_name
The actual name of the class.
The framework uses this ability to create new objects dynamically. For example, the new view created when you open a new document. Document, view, and frame classes should support dynamic creation because the framework needs to create them dynamically.
Add the DECLARE_DYNCREATE macro in the .h module for the class, then include that module in all .cpp modules that need access to objects of this class.
If DECLARE_DYNCREATE is included in the class declaration, then IMPLEMENT_DYNCREATE must be included in the class implementation.
For more information on the DECLARE_DYNCREATE macro, see CObject Class Topics.
Note
The DECLARE_DYNCREATE macro includes all the functionality of DECLARE_DYNAMIC.
See the example for IMPLEMENT_DYNCREATE.
Header: afx.h
Declares the GetUserTypeNameID and GetMiscStatus member functions of your control class.
DECLARE_OLECTLTYPE( class_name )
class_name
The name of the control class.
GetUserTypeNameID and GetMiscStatus are pure virtual functions, declared in COleControl. Because these functions are pure virtual, they must be overridden in your control class. In addition to DECLARE_OLECTLTYPE, you must add the IMPLEMENT_OLECTLTYPE macro to your control class declaration.
Header: afxctl.h
Declares that the OLE control provides a list of property pages to display its properties.
DECLARE_PROPPAGEIDS( class_name )
class_name
The name of the control class that owns the property pages.
Use the DECLARE_PROPPAGEIDS macro at the end of your class declaration. Then, in the .cpp file that defines the member functions for the class, use the BEGIN_PROPPAGEIDS macro, macro entries for each of your control's property pages, and the END_PROPPAGEIDS macro to declare the end of the property page list.
For more information on property pages, see the article ActiveX Controls: Property Pages.
Header: afxctl.h
BEGIN_PROPPAGEIDS
END_PROPPAGEIDS
Generates the C++ header code necessary for a CObject-derived class that can be serialized.
DECLARE_SERIAL(class_name)
class_name
The actual name of the class.
Serialization is the process of writing or reading the contents of an object to and from a file.
Use the DECLARE_SERIAL macro in an .h module, and then include that module in all .cpp modules that need access to objects of this class.
If DECLARE_SERIAL is included in the class declaration, then IMPLEMENT_SERIAL must be included in the class implementation.
The DECLARE_SERIAL macro includes all the functionality of DECLARE_DYNAMIC and DECLARE_DYNCREATE.
You can use the AFX_API macro to automatically export the CArchive extraction operator for classes that use the DECLARE_SERIAL and IMPLEMENT_SERIAL macros. Bracket the class declarations (located in the .h file) with the following code:
[!code-cppNVC_MFCCObjectSample#20]
For more information on the DECLARE_SERIAL macro, see CObject Class Topics.
[!code-cppNVC_MFCCObjectSample#21]
Header: afx.h
Generates the C++ code necessary for a dynamic CObject-derived class with run-time access to the class name and position within the hierarchy.
IMPLEMENT_DYNAMIC(class_name, base_class_name)
class_name
The actual name of the class.
base_class_name
The name of the base class.
Use the IMPLEMENT_DYNAMIC macro in a .cpp module, and then link the resulting object code only once.
For more information, see CObject Class Topics.
[!code-cppNVC_MFCCObjectSample#2]
[!code-cppNVC_MFCCObjectSample#3]
Header: afx.h
Enables objects of CObject-derived classes to be created dynamically at run time when used with the DECLARE_DYNCREATE macro.
IMPLEMENT_DYNCREATE(class_name, base_class_name)
class_name
The actual name of the class.
base_class_name
The actual name of the base class.
The framework uses this ability to create new objects dynamically, for example, when it reads an object from disk during serialization. Add the IMPLEMENT_DYNCREATE macro in the class implementation file. For more information, see CObject Class Topics.
If you use the DECLARE_DYNCREATE and IMPLEMENT_DYNCREATE macros, you can then use the RUNTIME_CLASS macro and the CObject::IsKindOf member function to determine the class of your objects at run time.
If DECLARE_DYNCREATE is included in the class declaration, then IMPLEMENT_DYNCREATE must be included in the class implementation.
Note that this macro definition will invoke the default constructor for your class. If a non-trivial constructor is explicitly implemented by the class, it must also explicitly implement the default constructor as well. The default constructor can be added to the class's private or protected member sections to prevent it from being called from outside the class implementation.
[!code-cppNVC_MFCCObjectSample#22]
[!code-cppNVC_MFCCObjectSample#23]
Header: afx.h
Either this macro or IMPLEMENT_OLECREATE must appear in the implementation file for any class that uses DECLARE_OLECREATE.
IMPLEMENT_OLECREATE_FLAGS( class_name, external_name, nFlags,
l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8)
class_name
The actual name of the class.
external_name
The object name exposed to other applications (enclosed in quotation marks).
nFlags
Contains one or more of the following flags:
-
afxRegInsertableAllows the control to appear in the Insert Object dialog box for OLE objects. -
afxRegApartmentThreadingSets the threading model in the registry to ThreadingModel=Apartment. -
afxRegFreeThreading Sets the threading model in the registry to ThreadingModel=Free.
You can combine the two flags
afxRegApartmentThreadingandafxRegFreeThreadingto set ThreadingModel=Both. See InprocServer32 in the Windows SDK for more information on threading model registration.
l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8
Components of the class's CLSID.
Note
If you use IMPLEMENT_OLECREATE_FLAGS, you can specify which threading model your object supports by using the nFlags parameter. If you want to support only the single-treading model, use IMPLEMENT_OLECREATE.
The external name is the identifier exposed to other applications. Client applications use the external name to request an object of this class from an automation server.
The OLE class ID is a unique 128-bit identifier for the object. It consists of one long, two WORDs, and eight BYTEs, as represented by l, w1, w2, and b1 through b8 in the syntax description. The Application Wizard and code wizards create unique OLE class IDs for you as required.
Header: afxdisp.h
Macros and Globals
DECLARE_OLECREATE
CLSID Key
Implements the GetUserTypeNameID and GetMiscStatus member functions of your control class.
DECLARE_OLECTLTYPE( class_name, idsUserTypeName, dwOleMisc )
class_name
The name of the control class.
idsUserTypeName
The resource ID of a string containing the external name of the control.
dwOleMisc
An enumeration containing one or more flags. For more information on this enumeration, see OLEMISC in the Windows SDK.
In addition to IMPLEMENT_OLECTLTYPE, you must add the DECLARE_OLECTLTYPE macro to your control class declaration.
The GetUserTypeNameID member function returns the resource string that identifies your control class. GetMiscStatus returns the OLEMISC bits for your control. This enumeration specifies a collection of settings describing miscellaneous characteristics of your control. For a full description of the OLEMISC settings, see OLEMISC in the Windows SDK.
Note
The default settings used by the ActiveX ControlWizard are: OLEMISC_ACTIVATEWHENVISIBLE, OLEMISC_SETCLIENTSITEFIRST, OLEMISC_INSIDEOUT, OLEMISC_CANTLINKINSIDE, and OLEMISC_RECOMPOSEONRESIZE.
Header: afxctl.h
Macros and Globals
DECLARE_OLECTLTYPE
Generates the C++ code necessary for a dynamic CObject-derived class with run-time access to the class name and position within the hierarchy.
IMPLEMENT_SERIAL(class_name, base_class_name, wSchema)
class_name
The actual name of the class.
base_class_name
The name of the base class.
wSchema
A UINT "version number" that will be encoded in the archive to enable a deserializing program to identify and handle data created by earlier program versions. The class schema number must not be -1.
Use the IMPLEMENT_SERIAL macro in a .cpp module; then link the resulting object code only once.
You can use the AFX_API macro to automatically export the CArchive extraction operator for classes that use the DECLARE_SERIAL and IMPLEMENT_SERIAL macros. Bracket the class declarations (located in the .h file) with the following code:
[!code-cppNVC_MFCCObjectSample#20]
For more information, see the CObject Class Topics.
[!code-cppNVC_MFCCObjectSample#24]
Header: afx.h
Gets the run-time class structure from the name of a C++ class.
RUNTIME_CLASS(class_name)
class_name
The actual name of the class (not enclosed in quotation marks).
RUNTIME_CLASS returns a pointer to a CRuntimeClass structure for the class specified by class_name. Only CObject-derived classes declared with DECLARE_DYNAMIC, DECLARE_DYNCREATE, or DECLARE_SERIAL will return pointers to a CRuntimeClass structure.
For more information, see CObject Class Topics.
[!code-cppNVC_MFCCObjectSample#25]
Header: afx.h
Enables objects of CCmdTarget-derived classes to be created through OLE automation.
DECLARE_OLECREATE(class_name)
class_name
The actual name of the class.
This macro enables other OLE-enabled applications to create objects of this type.
Add the DECLARE_OLECREATE macro in the .h module for the class, and then include that module in all .cpp modules that need access to objects of this class.
If DECLARE_OLECREATE is included in the class declaration, then IMPLEMENT_OLECREATE must be included in the class implementation. A class declaration using DECLARE_OLECREATE must also use DECLARE_DYNCREATE or DECLARE_SERIAL.
Header: afxdisp.h
Either this macro or IMPLEMENT_OLECREATE_FLAGS must appear in the implementation file for any class that uses DECLARE_OLECREATE.
IMPLEMENT_OLECREATE(class_name, external_name, l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8)
class_name
The actual name of the class.
external_name
The object name exposed to other applications (enclosed in quotation marks).
l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8
Components of the class's CLSID.
Note
If you use IMPLEMENT_OLECREATE, by default, you support only the single threading model. If you use IMPLEMENT_OLECREATE_FLAGS, you can specify which threading model your object supports by using the nFlags parameter.
The external name is the identifier exposed to other applications. Client applications use the external name to request an object of this class from an automation server.
The OLE class ID is a unique 128-bit identifier for the object. It consists of one long, two WORDs, and eight BYTEs, as represented by l, w1, w2, and b1 through b8 in the syntax description. The Application Wizard and code wizards create unique OLE class IDs for you as required.
Header: afxdisp.h