CRuntimeClass Structure

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CRuntimeClass Structure.

Each class derived from CObject is associated with a CRuntimeClass structure that you can use to obtain information about an object or its base class at run time.

struct CRuntimeClass  

Public Methods

NameDescription
CRuntimeClass::CreateObjectCreates an object during run time.
CRuntimeClass::FromNameCreates an object during run time using the familiar class name.
CRuntimeClass::IsDerivedFromDetermines if the class is derived from the specified class.

Public Data Members

NameDescription
CRuntimeClass::m_lpszClassNameThe name of the class.
CRuntimeClass::m_nObjectSizeThe size of the object in bytes.
CRuntimeClass::m_pBaseClassA pointer to the CRuntimeClass structure of the base class.
CRuntimeClass::m_pfnCreateObjectA pointer to the function that dynamically creates the object.
CRuntimeClass::m_pfnGetBaseClassReturns the CRuntimeClass structure (only available when dynamically linked).
CRuntimeClass::m_wSchemaThe schema number of the class.

CRuntimeClass is a structure and therefore does not have a base class.

The ability to determine the class of an object at run time is useful when extra type checking of function arguments is needed, or 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.

CRuntimeClass provides information on the related C++ object, such as a pointer to the CRuntimeClass of the base class and the ASCII class name of the related class. This structure also implements various functions that can be used to dynamically create objects, specifying the type of object by using a familiar name, and determining if the related class is derived from a specific class.

For more information on using CRuntimeClass, see the article Accessing Run-Time Class Information.

CRuntimeClass

Header: afx.h

Call this function to dynamically create the specified class during run time.

CObject* CreateObject();  
  
static CObject* PASCAL CreateObject(LPCSTR lpszClassName);  
  
static CObject* PASCAL CreateObject(LPCWSTR lpszClassName);

Parameters

lpszClassName
The familiar name of the class to be created.

Return Value

A pointer to the newly created object, or NULL if the class name is not found or there is insufficient memory to create the object.

Remarks

Classes derived from CObject can support dynamic creation, which is the ability to create an object of a specified class at run time. Document, view, and frame classes, for example, should support dynamic creation. For more information on dynamic creation and the CreateObject member, see CObject Class and CObject Class: Specifying Levels of Functionality.

Example

See the example for IsDerivedFrom.

Call this function to retrieve the CRuntimeClass structure associated with the familiar name.

static CRuntimeClass* PASCAL FromName(LPCSTR lpszClassName);  
  
static CRuntimeClass* PASCAL FromName(LPCWSTR lpszClassName);

Parameters

lpszClassName
The familiar name of a class derived from CObject.

Return Value

A pointer to a CRuntimeClass object, corresponding to the name as passed in lpszClassName. The function returns NULL if no matching class name was found.

Example

      // This example creates an object if CAge is defined.

      CRuntimeClass* pClass = CRuntimeClass::FromName(_T("CAge"));
      if (pClass == NULL)
      {
         // not found, display a warning for diagnostic purposes
         AfxMessageBox(_T("Warning: CMyClass not defined"));
         return NULL;
      }

      // attempt to create the object with the found CRuntimeClass
      CObject* pObject = pClass->CreateObject();

Call this function to determine if the calling class is derived from the class specified in the pBaseClass parameter.

BOOL IsDerivedFrom(const CRuntimeClass* pBaseClass) const;

 

Parameters

pBaseClass
The familiar name of a class derived from CObject.

Return Value

TRUE if the class calling IsDerivedFrom is derived from the base class whose CRuntimeClass structure is given as a parameter; otherwise FALSE.

Remarks

The relationship is determined by "walking" from the member's class up the chain of derived classes all the way to the top. This function only returns FALSE if no match is found for the base class.

System_CAPS_ICON_note.jpg Note

To use the CRuntimeClass structure, you must include the IMPLEMENT_DYNAMIC, IMPLEMENT_DYNCREATE, or IMPLEMENT_SERIAL macro in the implementation of the class for which you want to retrieve run-time object information.

For more information on using CRuntimeClass, see the article CObject Class: Accessing Run-Time Class Information.

Example

      // This example creates an object from the run-time class. It only 
      // creates objects derived from CWnd.

      // We only want to create an object derived from CWnd.
      if (!pClass->IsDerivedFrom(RUNTIME_CLASS(CWnd)))
      {
         TRACE(_T("Error; Object %s is not derived from CWnd\n"),
            pClass->m_lpszClassName);
         return FALSE;
      }

      // Get a pointer to the base class CRuntimeClass.
      #ifdef _AFXDLL
         CRuntimeClass* pBaseClass = pClass->m_pfnGetBaseClass();
      #else
         CRuntimeClass* pBaseClass = pClass->m_pBaseClass;
      #endif
      ASSERT(pBaseClass != NULL);

      TRACE("Creating object %s derived from %s, with object size %d "
         "and schema %d\n", pClass->m_lpszClassName, 
         pBaseClass->m_lpszClassName, pClass->m_nObjectSize, 
         pClass->m_wSchema);

      // Create the object.
      CObject* pObject = pClass->CreateObject();

A null-terminated string containing the ASCII class name.

Remarks

This name can be used to create an instance of the class using the FromName member function.

Example

See the example for IsDerivedFrom.

The size of the object, in bytes.

Remarks

If the object has data members that point to allocated memory, the size of that memory is not included.

Example

See the example for IsDerivedFrom.

If your application statically links to MFC, this data member contains a pointer to the CRuntimeClass structure of the base class.

Remarks

If your application dynamically links to the MFC library, see m_pfnGetBaseClass.

Example

See the example for IsDerivedFrom.

A function pointer to the default constructor that creates an object of your class.

Remarks

This pointer is only valid if the class supports dynamic creation; otherwise, the function returns NULL.

If your application uses the MFC library as a shared DLL, this data member points to a function that returns the CRuntimeClass structure of the base class.

Remarks

If your application statically links to the MFC library, see m_pBaseClass.

Example

See the example for IsDerivedFrom.

The schema number ( -1 for nonserializable classes).

Remarks

For more information on schema numbers, see the [IMPLEMENT_SERIAL]--brokenlink--(../Topic/not%20found.md#implement_serial) macro.

Example

See the example for IsDerivedFrom.

Hierarchy Chart
CObject::GetRuntimeClass
CObject::IsKindOf
[RUNTIME_CLASS]--brokenlink--(../Topic/not%20found.md#runtime_class)
[IMPLEMENT_DYNAMIC]--brokenlink--(../Topic/not%20found.md#implement_dynamic)
[IMPLEMENT_DYNCREATE]--brokenlink--(../Topic/not%20found.md#implement_dyncreate)
[IMPLEMENT_SERIAL]--brokenlink--(../Topic/not%20found.md#implement_serial)

Show: