| 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 | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
CObject Class | Microsoft Docs |
11/04/2016 |
|
reference |
|
|
|
95e9acd3-d9eb-4ac0-b52b-ca4a501a7a3a |
22 |
mikeblome |
mblome |
ghogen |
The principal base class for the Microsoft Foundation Class Library.
class AFX_NOVTABLE CObject
| Name | Description |
|---|---|
| CObject::CObject | Default constructor. |
| Name | Description |
|---|---|
| CObject::AssertValid | Validates this object's integrity. |
| CObject::Dump | Produces a diagnostic dump of this object. |
| CObject::GetRuntimeClass | Returns the CRuntimeClass structure corresponding to this object's class. |
| CObject::IsKindOf | Tests this object's relationship to a given class. |
| CObject::IsSerializable | Tests to see whether this object can be serialized. |
| CObject::Serialize | Loads or stores an object from/to an archive. |
| Name | Description |
|---|---|
| CObject::operator delete | Special delete operator. |
| CObject::operator new | Special new operator. |
It serves as the root not only for library classes such as CFile and CObList, but also for the classes that you write. CObject provides basic services, including
-
Serialization support
-
Run-time class information
-
Object diagnostic output
-
Compatibility with collection classes
Note that CObject does not support multiple inheritance. Your derived classes can have only one CObject base class, and that CObject must be leftmost in the hierarchy. It is permissible, however, to have structures and non- CObject-derived classes in right-hand multiple-inheritance branches.
You will realize major benefits from CObject derivation if you use some of the optional macros in your class implementation and declarations.
The first-level macros, DECLARE_DYNAMIC and IMPLEMENT_DYNAMIC, permit run-time access to the class name and its position in the hierarchy. This, in turn, allows meaningful diagnostic dumping.
The second-level macros, DECLARE_SERIAL and IMPLEMENT_SERIAL, include all the functionality of the first-level macros, and they enable an object to be "serialized" to and from an "archive."
For information about deriving Microsoft Foundation classes and C++ classes in general and using CObject, see Using CObject and Serialization.
CObject
Header: afx.h
Validates this object's integrity.
virtual void AssertValid() const;
AssertValid performs a validity check on this object by checking its internal state. In the Debug version of the library, AssertValid may assert and thus terminate the program with a message that lists the line number and filename where the assertion failed.
When you write your own class, you should override the AssertValid function to provide diagnostic services for yourself and other users of your class. The overridden AssertValid usually calls the AssertValid function of its base class before checking data members unique to the derived class.
Because AssertValid is a const function, you are not permitted to change the object state during the test. Your own derived class AssertValid functions should not throw exceptions but rather should assert whether they detect invalid object data.
The definition of "validity" depends on the object's class. As a rule, the function should perform a "shallow check." That is, if an object contains pointers to other objects, it should check to see whether the pointers are not null, but it should not perform validity testing on the objects referred to by the pointers.
See CObList::CObList for a listing of the CAge class used in all CObject examples.
[!code-cppNVC_MFCCObjectSample#7]
For another example, see AfxDoForAllObjects.
These functions are the standard CObject constructors.
CObject();
CObject(const CObject& objectSrc);
objectSrc
A reference to another CObject
The default version is automatically called by the constructor of your derived class.
If your class is serializable (it incorporates the IMPLEMENT_SERIAL macro), then you must have a default constructor (a constructor with no arguments) in your class declaration. If you do not need a default constructor, declare a private or protected "empty" constructor. For more information, see Using CObject.
The standard C++ default class copy constructor does a member-by-member copy. The presence of the private CObject copy constructor guarantees a compiler error message if the copy constructor of your class is needed but not available. You must therefore provide a copy constructor if your class requires this capability.
See CObList::CObList for a listing of the CAge class used in the CObject examples.
[!code-cppNVC_MFCCObjectSample#8]
Dumps the contents of your object to a CDumpContext object.
virtual void Dump(CDumpContext& dc) const;
dc
The diagnostic dump context for dumping, usually afxDump.
When you write your own class, you should override the Dump function to provide diagnostic services for yourself and other users of your class. The overridden Dump usually calls the Dump function of its base class before printing data members unique to the derived class. CObject::Dump prints the class name if your class uses the IMPLEMENT_DYNAMIC or IMPLEMENT_SERIAL macro.
Note
Your Dump function should not print a newline character at the end of its output.
Dump calls make sense only in the Debug version of the Microsoft Foundation Class Library. You should bracket calls, function declarations, and function implementations with #ifdef _DEBUG/ #endif statements for conditional compilation.
Since Dump is a const function, you are not permitted to change the object state during the dump.
The CDumpContext insertion (<<) operator calls Dump when a CObject pointer is inserted.
Dump permits only "acyclic" dumping of objects. You can dump a list of objects, for example, but if one of the objects is the list itself, you will eventually overflow the stack.
See CObList::CObList for a listing of the CAge class used in all CObject examples.
[!code-cppNVC_MFCCObjectSample#9]
Returns the CRuntimeClass structure corresponding to this object's class.
virtual CRuntimeClass* GetRuntimeClass() const;
A pointer to the CRuntimeClass structure corresponding to this object's class; never NULL.
There is one CRuntimeClass structure for each CObject-derived class. The structure members are as follows:
-
LPCSTR m_lpszClassName A null-terminated string containing the ASCII class name.
-
int m_nObjectSize The size of the object, in bytes. If the object has data members that point to allocated memory, the size of that memory is not included.
-
UINT m_wSchema The schema number ( - 1 for nonserializable classes). See the IMPLEMENT_SERIAL macro for a description of schema number.
-
CObject* ( PASCAL* m_pfnCreateObject )( ) A function pointer to the default constructor that creates an object of your class (valid only if the class supports dynamic creation; otherwise, returns NULL).
-
CRuntimeClass* ( PASCAL* m_pfn_GetBaseClass )( ) If your application is dynamically linked to the AFXDLL version of MFC, a pointer to a function that returns the
CRuntimeClassstructure of the base class. -
CRuntimeClass* m_pBaseClass If your application is statically linked to MFC, a pointer to the
CRuntimeClassstructure of the base class.
This function requires use of the IMPLEMENT_DYNAMIC, IMPLEMENT_DYNCREATE, or IMPLEMENT_SERIAL macro in the class implementation. You will get incorrect results otherwise.
See CObList::CObList for a listing of the CAge class used in all CObject examples.
[!code-cppNVC_MFCCObjectSample#10]
Tests this object's relationship to a given class.
BOOL IsKindOf(const CRuntimeClass* pClass) const;
pClass
A pointer to a CRuntimeClass structure associated with your CObject-derived class.
Nonzero if the object corresponds to the class; otherwise 0.
This function tests pClass to see if (1) it is an object of the specified class or (2) it is an object of a class derived from the specified class. This function works only for classes declared with the DECLARE_DYNAMIC, DECLARE_DYNCREATE, or DECLARE_SERIAL macro.
Do not use this function extensively because it defeats the C++ polymorphism feature. Use virtual functions instead.
See CObList::CObList for a listing of the CAge class used in all CObject examples.
[!code-cppNVC_MFCCObjectSample#11]
Tests whether this object is eligible for serialization.
BOOL IsSerializable() const;
Nonzero if this object can be serialized; otherwise 0.
For a class to be serializable, its declaration must contain the DECLARE_SERIAL macro, and the implementation must contain the IMPLEMENT_SERIAL macro.
Note
Do not override this function.
See CObList::CObList for a listing of the CAge class used in all CObject examples.
[!code-cppNVC_MFCCObjectSample#12]
For the Release version of the library, operator delete frees the memory allocated by operator new.
void PASCAL operator delete(void* p);
void PASCAL operator delete(
void* p,
void* pPlace);
void PASCAL operator delete(
void* p,
LPCSTR lpszFileName,
int nLine);
In the Debug version, operator delete participates in an allocation-monitoring scheme designed to detect memory leaks.
If you use the code line
[!code-cppNVC_MFCCObjectSample#14]
before any of your implementations in a .CPP file, then the third version of delete will be used, storing the filename and line number in the allocated block for later reporting. You do not have to worry about supplying the extra parameters; a macro takes care of that for you.
Even if you do not use DEBUG_NEW in Debug mode, you still get leak detection, but without the source-file line-number reporting described above.
If you override operators new and delete, you forfeit this diagnostic capability.
See CObList::CObList for a listing of the CAge class used in the CObject examples.
[!code-cppNVC_MFCCObjectSample#15]
For the Release version of the library, operator new performs an optimal memory allocation in a manner similar to malloc.
void* PASCAL operator new(size_t nSize);
void* PASCAL operator new(size_t, void* p);
void* PASCAL operator new(
size_t nSize,
LPCSTR lpszFileName,
int nLine);
In the Debug version, operator new participates in an allocation-monitoring scheme designed to detect memory leaks.
If you use the code line
[!code-cppNVC_MFCCObjectSample#14]
before any of your implementations in a .CPP file, then the second version of new will be used, storing the filename and line number in the allocated block for later reporting. You do not have to worry about supplying the extra parameters; a macro takes care of that for you.
Even if you do not use DEBUG_NEW in Debug mode, you still get leak detection, but without the source-file line-number reporting described above.
Note
If you override this operator, you must also override delete. Do not use the standard library _new_handler function.
See CObList::CObList for a listing of the CAge class used in the CObject examples.
[!code-cppNVC_MFCCObjectSample#16]
Reads or writes this object from or to an archive.
virtual void Serialize(CArchive& ar);
ar
A CArchive object to serialize to or from.
You must override Serialize for each class that you intend to serialize. The overridden Serialize must first call the Serialize function of its base class.
You must also use the DECLARE_SERIAL macro in your class declaration, and you must use the IMPLEMENT_SERIAL macro in the implementation.
Use CArchive::IsLoading or CArchive::IsStoring to determine whether the archive is loading or storing.
Serialize is called by CArchive::ReadObject and CArchive::WriteObject. These functions are associated with the CArchive insertion operator ( <<) and extraction operator ( >>).
For serialization examples, see the article Serialization: Serializing an Object.
See CObList::CObList for a listing of the CAge class used in all CObject examples.
[!code-cppNVC_MFCCObjectSample#13]