The CArchive of MFC class Library

There is no base class for the CArchive CArchive of the MFC class library. CArchive allows a complex network of objects to be saved in the form of a permanent binary (typically disk storage), which can be persisted when the object is deleted. You can mount objects from persistent storage and reconstruct them in memory. The process of making data permanent is called serialization. You can think of an archive object as a binary stream. Like input/output streams, archiving is related to files and allows write buffers as well as read-out or read-in data from the hard disk. The input/output stream processes a series of ASCII characters, but the archive handles binary objects in an efficient, concise format. You must create a CFile object before you create a CArchive object. In addition, you must be sure that the file's Mount/store is compatible with the open mode of the files. Each file is limited to one active archive file. When constructing a CArchive object, attach it to an object representing the class CFile (or derived class) that represents an open file. Also specify whether the archive will be used for mounting or storage. The CArchive object can handle not only the primary type, but also the object of the Cobject_ derived class designed for serialization. A serialized class typically has a serialize member function and uses declare_serial and IMPLEMENT_SERIAL macros. These are described in the CObject class. Overload extraction (>>) and insertion (<<) are convenient archiving programming interfaces. It supports both primary types and CObject derived classes. CArchive also supports programming with the MFC Windows Sockets class CSocket and CSocketFile. The IsBufferEmpty member function also supports this use. If you want to learn more about CArchive, see "Serialization (Persistent objects)" and "Windows Sockets: Using sockets in an archive file" in the online documentation "Visual C + + Programmer's Guide." #include See member data members of the Cfile,cobject,csocket,csocketfile CArchive class m_pdocument point to the CDocument object constructor that is serialized CArchive Create a Carhcive object abort in the case of no exception, close the archive file to dismiss the data that is not written and release the connection to the CFile basic input/output flush from the archive file buffer to flush out the non-write data operator >> Main type operators for loading objects and archive files << main types of storage objects and archives read reading into original type WrIte writes the original type WriteString writes a line of text ReadString reads a line of text state GetFile obtains the CFile object pointer for this archive GetObjectSchema the Serialize function call to determine the version of the object that is not serialized Setobjectschema store an Object profile in an archive isloading determine if the archive is loaded isstoring determine if the archive is stored isbufferempty determine if it is in a Windows Whether the buffer is emptied during socket receive object input/output ReadObject call a serialize function for loading writeobect call a serialize function for loading MapObject object is placed in a map that does not serialize the file, but this mapping is valid for the referenced sub-object Setstoreparams sets the size of the hash table and the size of the mapped block, recognizes unique objects during serialization Loadparams sets the size of the Mount array extension. You must readclass read a reference to a class that was previously stored in WriteClass before the object is loaded or before calling MapObject or ReadObject WriteClass write a reference to Cruntime SerializeClass a reference member function that reads or writes to the CArchive object's class according to CArchive direction carchive::abort void Abort (); Description call this function to close the archive file without exception. The CArchive destructor will call Close, and it will flush out any data that is not stored in the related CFile object. This can cause an exception. When getting these exceptions, there is a good way to use abort, so that the destructor CArchive object will no longer cause an exception. When an exception is handled, Carchive::abort will not be an exception on failure because, unlike Carchive::clsoe, Abort ignores the failure. If you use new to allocate a CArchive object on the heap, you must delete it after you close the file. See Carchive::close,cfile::close carchive::carchive CArchive (cfile*pfile,uintnmode,int nbufsize=4096,void*lpbuf= NULL); throw (cmemoryexception,carchiveexception,cfileException); A pointer to the parameter Pfilecfile object. The CFile object is the final source or destination of the persistent data. Nmode identification. It specifies whether the object is loaded or stored in the file from the archive file. The Nmode parameter must have one of the following values: L carchive::load load data from an archive file. CFile read-only. L Carchive::store Save the data to the archive file. Allow CFile write operations. L Carchive::bnoflushondelete prevents the archive file from automatically calling flush when the archive destructor is called. If this identity is set, it must be responsible for calling close before the destructor is called. If you do not do this, the data will crash. Nbufsize An integer that specifies the size of the internal file buffer, in bytes. Note The default buffer size is 4096 bytes. If the routines archive large objects, using larger buffers, or multiple file buffers, the routines will be more efficient to execute. Lpbuf A pointer to the nbufsize size of the supplied buffer. If this parameter is not specified, the archive allocates a buffer to the archive file from the local heap and releases the buffer when the object is destroys. The archive file cannot release a supplied buffer. Description constructs a CArchive object and specifies that it will be used to mount or store the object. The specified content cannot be changed after the archive has been created. You cannot use the CFile action to change the state of a file until you have closed the archive file. Any such operation will destroys the integrity of the archive file. The file object that obtains the archive file by the GetFile member function makes it possible to access the position of the file pointer at any time during serialization. Then use the Cfile::getposition function. The Carchive::flush should be called before the file pointer position is obtained. Example extern char* pfilename CFile F; Char buf[512]; if (!f.open (pfilename,cfile::modecreate| Cfile::modewrite) {#ifdef_DEBUG afxdump<< "Unable to open file" << "/n"; exit (1); #endif} CArchive ar (&f , CACHIVE::STRORE,512,BUF); See Carchive::close,carchive::flush,cfile::close carchive::close void Close () throw (carchiveexception,cfileexception); Description flushes out any data saved in the buffer, closes the archive, and releases the link to the archive file. There are no other actions allowed for the archive file. After you close an archive file, you can create another archive or close the file for one of the same files. The member function close ensures that all data is transferred from the archive file to the file and invalidates the archive file. To complete the transfer from file to storage media, you must first use CFile::Close and then destroys the CFile object. See Carchive::flush,carchive::abort Carchive::flush void Flush (); throw (CFileException); Description forces the data that is kept in the archive file to be written to the file. The member function flush guarantees that all data is transferred from the archive file to the file. You must call CFile::Close to complete the transfer from file to storage media. See Carchive::close,cfile::flush,cfile::close Carchive::getfile cfile* GetFile () const; The return value points to a pointer to the CFile object being used. Describes obtaining a CFile object pointer for this archive file. The archive must be flushed before using GetFile. example extern CArchive ar; Const Cfile*fp=ar. GetFile (); See Carchive::flush CArchive::GetObjectSchema UINT GetObjectSchema (); The return value returns the version of the object that was read into the non-serialization process. Note This function is called by the Serialize function to determine the version of an object that is currently not serialized. Calling this function is valid when the CArchive object is being loaded (carchive::isloading returns a value other than 0). It must be the first call of the Serialize function and can only be called once. The return value -1 (UINT) indicates that the version number is unknown. The CObject derived class can use the Versionable_sehema that is used in conjunction with the outline version itself (in the IMPLEMENT_SERIALH macro) to create a "versioned object" that is an object whose member functions can be read into multiple versions. When the version does not match, the default frame function (without versionable_shema) will signal the exception. Example Implement_seriaL (cmyobject,cobject,versioanable_schema|1) void Cmyobject::serialize (carchive& ar) {if (AR. IsLoading ()) {int Nversion=ar. Getobjectschma (); Switch (nversion) {case 0://read in previous version of//this object broke; Case 1://read in current version of//this Object break; Default://report unknown version of//this object break; }} else {//normal soring code goes here}} see Cobject::serialize,cobject::isserializable,implemnet_serial,declare_seri Al,carchive::isloading carchive::isbufferempty BOOL isbufferempty () const; Return value if the archive's buffer is empty, it returns a value other than 0, otherwise 0. Description call this function to determine if the buffer for the archive file is empty. This function supports programming with the Windows Sockets class CSocketFile. You do not need to use it for an archive file that is related to an CFile object. The archive file associated with the CSocketFile object uses IsBufferEmpty because the archive's buffer may contain multiple messages or records. When receiving a message, you should use IsBufferEmpty to control such a loop, which continuously receives data until the buffer is empty. If you want to learn more, see the rceive member function for class CAsyncSocket and the MFC Advanced Concepts sample CHATSRVR, which will show you how to use IsBufferEmpty. For more information, see "Windows Sockets: Using Sockets in an archive" in the online documentation, "Visual C + + Programmer's Guide." See Csocketfile,casyncsocket::receive carchive::isloading BOOL isloading () const return value if the archive is being loadedFile, it returns a value other than 0, otherwise 0. Description Determines whether the archive file is loading data. This member function is called by the Serialize function of the archive class. example int i; extern CArchive ar; if (AR. IsLoading ()) ar>>i; else AR << i; See carchive::isstoring carchive::isstoring BOOL isstorng () const; Return value if the archive is being stored, a value other than 0 is returned, otherwise 0. Description Determines whether the archive file is being stored. This function is called by the Serialize function of the archive class. If the isstoring status of the archive is nonzero, its isloading status is 0 and vice versa. example int i; extern CArchive ar; if (AR. IsStoring ()) ar<>i; See carchive::isloading Carchive::mapobject void MapObject (const COBJECT*POB); The POb parameter points to a pointer to the object being stored. Description call this member function to place the object in the map. This mapping does not really serialize the file, but is valid for the referenced sub-object. For example, you might not want to serialize a document, but you want to serialize the items that are part of the document. By calling MapObject, you can allow those items or sub-objects to reference the document. Also, serialization subkeys can serialize their m_pdocument backward pointers. You can call MapObject when you want to store data in a CArchive object and load data from it. During serialization and non-serialization, MapObject adds specific objects to the internal data structures maintained by CArchive, but it does not serialize objects like ReadObject and WriteObject. Example//mydoc.h//document should have declear_serial and Implement_serial class Cmydocument:public CDocument {CObList M_li Stofsubitems; ... Declare_serial (Cmydocument)}; MyDoc.cpp ... Mplement_serial (cmydocument.cobject,1) ... voID cmydocument::serialize (carchive& ar) {if (AR. IsStoring ()) {//todo:add Storing code here}else {//todo:add loading code here} ar. MapObject (this); Serialize the subitems in the documents; They'll be able to serialize their M_pdoc//back pointer m_listofsubitems.serialize (AR); }//subitem.h class Csubitem:public CObject {public Csubitem (Cmydocument * Pdoc) {M_pdoc=pdoc}//back pointer to owning Document Cmydocument* M_pdoc; WORD m_i; Other item data virtual void Serialize (carchive& ar); }; SubItem.cpp void Csubitem:serialize (carchive& ar) {if (AR. IsStoring ()) {//will serializing a reference//to the mapped to document Pointer ar <>m_pDoc; ar >>m_i;}} See Carchive::readobject,carchive::writeobject carchive::read UINT Read (Void*lpbuf,uint nMax); throw (CFileException); The return value contains an unsigned integer that is actually read into the number of bytes. If the return value is less than the desired value, the end of the file is reached. There is no exception when the end of the file is reached. The LPBUF parameter points to a pointer to the provided buffer. This provided buffer receives the data read from the archive file. NMax An unsigned pointer that indicates the number of bytes read from the archive file. Description reads the specified number of bytes from the archive file. The archive file does not interpret the number of bytes. You can use r in the Serialize function.The EAD member function reads the normal structure contained in the object. example extern CArchive ar; Char pb[100]; UINT Nr=ar. Read (pb.100); Carchive::readclass Cruntimeclass*readclass (Construntimeclass*pclassrefrequested=null, UINT* PSchema=NULL, DWORD* Obtag=null); Throw carchiveexception; Throw cnotsupportedexception; The return value points to a pointer to the CRUNTIMECLASS structure. The pclassrefrequested parameter points to a pointer to the CRUNTIMECLASS structure that corresponds to the reference of the class you want. can be null. Pschema a pointer to the outline of the previously stored run-time class. Obtag represents a numeric value that uniquely identifies an object. It is used internally through the implementation of the ReadObject. For advanced programming only. The obtag should normally be null. Description call this member function to read a reference to a class that was originally stored in WriteClass. If Pclassrefreguested does not prove to null,readclass that the archived file class information is compatible with the routine class. If incompatible, ReadClass will produce a carchiveexception. Routines must use declare_serial and implement_serial, otherwise readclass will produce a cnotsupportedexception. If Pschema is null, the storage class's outline can be recovered by calling CArchive::GetObjectSchema, otherwise *pschema will contain the outline of the previously stored run-time class. You can use SerializeClass instead of ReadClass, which handles reading and writing of class references. See CARCHIVE::WRITECLASS,CARCHIVE::GETOBJECTSCHEMA,CARCHIVE::SETOBJECTSCHEMA,CARCHIVEEXCEPTI_ON, Cnotsupportedexception,carchive::serializeclass carchive::readobject cobject*readobject (const CRUNTIMECLASS*PCLASS); throw (cfileexception,carchiveexception,cmemoryexception); Returns the value of the CObject pointer. It must safely point to the current derived class by using CObject::IsKindOf. The parameter pClass a constant pointer to the CRUMTIMECLASS structure. This structure corresponds to the object that is expected to be read in. Description reads an object from an archive file and constructs an object of the appropriate type. This function is typically called by the CArchive extract (>>) operator to overload a CObject pointer. ReadObject, in turn, calls the Serlialize function of the archive class. If a nonzero pclass parameter is supplied, it can be obtained from runtime_class, then the function confirms the running class of the archive file. Assume that the IMPLEMENT_SERIAL macro is already in use in the implementation of the class. See Carchive::writeobject,cobject::iskindof carchive::readstring Bool ReadString (cstring&rstring); LPTSTR ReadString (LPTSTR lpsz,uint nMax); throw (carchiveexception); The return value in the version that returns the logical value, True indicates success; false instead. In the version that returns LPTSTR, LPTSTR is a pointer to a buffer that contains literal data, and null represents the end of the file. A reference to the parameter rString CString. CString will contain the result string read out from the file associated with the CArchive object. LPSZ specifies a pointer to the provided buffer. This buffer will receive a text string ending with a null terminator. NMAX Specifies the maximum number of read-in characters. It does not allow smaller than the size of the lpsz buffer. The description calls this function to read the data from the file associated with the CArchive object and put it into the buffer. In the version of the member function with the Nmax parameter, the buffer has a maximum of nMax-1 characters. The read-in operation is terminated by a carriage return newline character. The characters following the new line symbol are discarded. In each case, there is a null character ("/0"). Carchive::read is also valid for text-mode input, but it does not terminate with a carriage return newline character. See Carchive::read,carchive::writestring,carchiveexception CARCHIVE::SERIALIZECLASSVOID serializeclass (const cruntimeclass*pruntimeclass); The Pruntimeclass parameter refers to a pointer to the base class's running class object. Describes calling this member function when you want to store and load version information for a base class. SerializeClass reading or writing a reference to a class on a CArchive object depends on the direction of the CArchive. Using SerializeClass instead of ReadClass and writeclass can make it easier to serialize base class objects. Because SerializeClass requires less code and parameters. Like ReadClass, SerializeClass proves that the archived file information is compatible with the routine class. If it is not compatible, SerializeClass will be a carchiveexception. The run class must use Declare_serial and implement_serial, otherwise serializeclass will be a cnotsupportexception. Use the Rumtime_class macro to restore the value of the Pruntimeclass parameter. The base class must already use the IMPLEMENT_SERIAL macro. Example Class Cbaseclass:public cobject{...}; Class Cderivedclass:public cbaseclass{...}; void Cderivedclass::serialize (carchive& ar) {if (AR. IsStoring ()) {//normal code for storing contents//of this object} else {//normal code for reading contents//of this Object}//allow the base class to serialize along//with its version information AR. SerializeClass (Runtime_class (Cbaseclass)); Cbaseclass::serialize (AR); See Carchive::readclass,carchive::writeclass,carchive::getobjectschema,carchive::setobjectsch_ema, carchiveexception,cnotsupportexception carchive::setloadparams void Setloadparams (UINT ngrowby=1024); Parameter Ngrowby if the capacity has to be enlarged, this is the smallest fraction of the allocated element. Describes calling Setloadparams when a large number of CObject derived objects are to be read by an archive file. CArchive uses an array of mounts to resolve references to objects stored in an archive file. Setloadparams allows you to set the size of the Mount array extension. You do not need to call Setloadparams after you mount any objects or call MapObject or call ReadObject. Example Class Cmylargedocument:public cdocument{...}; void Cmylargedocument::serialize (carchive& ar) {if (AR. IsStoring ()) AR. Setstoreparams ();//use large defaulte else ar. Setloadparams (); if (AR. IsStoring ()) {//code for storing cmylargedocument}else {//code for loading cmylargedocument}} See Cachive::setstorep Arams Carchive::setloadschema void Setloadschema (UINT nschema); The Nschema parameter specifies the outline of the object. Description call this member function to set the outline of the object that is stored in the archive file. Put this setting value in Nschema. A second call to GetObjectSchema returns the value stored in the Nschema. Setobjectschema can be used in advanced versions: for example, when you want to read a special version in the Serialize function of a derived class. See CArchive::GetObjectSchema carchive::setstoreparams void Setstoreparams (UINT nhashsize=2053,uint nBlockSize=128); Parameter nhashsize the size of the hash table used for the pointer-mapped interface, which must be a prime number. NBLOCKSIZE Specifies the memory allocation interval for the extension parameter. To get the best performance, it should be a multiple of 2. Describes the use of Setstoreparams when storing many CObject derived objects in an archive file. Setstoreparams allows you to set the size of the hash table and the size of the mapped block. Mappings are used to identify unique objects during serialization. You do not need to call Setstoreparams after you store any of the objects or call MapObject or writeobject. Example class Cmylargedocument:public cdocument{}; void Cmylargedocument::serialize (carchive& ar) {if (AR. IsStoring ()), AR. Setstoreparams ();//use large defaults else ar. Setloadparams (); if (AR. IsStoring ()) {//code for storing cmylargedocument}else {//code for loading cmylargedocument}} See CARCHIVE::SETLOADP Arams carchive::write void Write (const void*lpbuf,uint NMAX); throw (CFileException); The LPBUF parameter points to a pointer to the provided buffer. The buffer contains the data that will be written to the archive file. NMax An integer that specifies the number of bytes to be written to the archive file. Describes writing a specific number of bytes to an archive file. The archive file does not format bytes. You can use the Write member function in the Serialize function to write a generic structure that is contained in an object. example extern CArchive ar; Char pb[100]; Ar. Write (pb.100); See Carchive::read Carchive::writeclass void WriteClass (const cruntimeclass*pclassref); The Pclassref parameter points to a pointer to the CRUNTIMECLASS structure. This structure corresponds to the reference of the required class. Describes the use of WriteClass to store version and class information for a base class during serialization of a derived class. WriteClass the Cruntimec of the base classLass Reference write CArchive. Use the Carchive::readclass recovery reference. WriteClass proves that the archived file information is compatible with the routine class. If not compatible, WriteClass will carchive::exception. Routines must use Declare_serial and implement_serial. Otherwise, WriteClass will be a cnotsuppotedexception. You can use SerializeClass instead of WriteClass, which handles reading and writing of class references. See Carchive::readclass,carchive::getobjectschema,carchive::setobjectschema,cachive::serializ_eclass, Carchiveexception,cnotsupportexception. carchive::writeobject void WriteObject (const COBJECT*POB); throw (cfileexception,carchiveexception); The parameter pOb a constant pointer to the object being stored. Instructions to store specific CObject in an archive file. This function is typically called by the CArchive Insert (<<) operator of the overloaded CObject. WriteClass, in turn, calls the Serialize function of the archive class. You must use the IMPLEMENT_SERIAL macro archive. WriteObject writes the ASCII class name to the archive file. This class name is validated after the load process. A specific coding design prevents unnecessary reuse of multiple object class names. It also prevents excess storage of objects that are multiple pointers to targets. The correct object encoding method (included in the current ASCII class name) is an implementation detail and can be changed in later versions of the library. Note Before you archive, end the creation, deletion, and modification of all objects. If you mix the archive with the object modification, the archive will be discarded. See Carchive::readobject carchive::writestring void WriteString (LPCTSTR lpsz); throw (CFileException); The parameter lpsz uses this member function to write data from a buffer to the file associated with the CArchive object. The end of the null character ('/0 ') is not written to the file and the new line is not automatically written. Description WriteString can be used for several situationsexceptions, including when the disk is full. Write is still valid, but does not end with a null terminator, but rather it writes the required number of bytes to the file. See carchive::write,carchive::read,carchive::readstring,cfileexception operator carchive::operator<< Friend carchive& operator<< (carchive& ar,const cobject* pOb); throw (carchiveexception,cfileexception); carchive&operator<< (BYTE by); throw (carchiveexception,cfileexception); carchive&operator<< (WORD W); throw (carchiveexception,cfileexception); carchive&operator<< (int i); throw (carchiveexception,cfileexception); carchive&operator<< (LONG L); throw (carchiveexception,cfileexception); carchive&operator<< (DWORD DW); throw (carchiveexception,cfileexception); carchive&operator<< (float f); throw (carchiveexception,cfileexception); carchive&operator<< (double D); throw (carchiveexception,cfileexception); The return value CArchive reference, which can use multiple extraction operators on a single line. The description stores the exact object or primary type in the archive file. If you use the IMPLEMENT_SERIAL macro in the implementation of the class, then overload the CObject insert operator to invoke the protected writeobject. This function in turn invokes the Serialize function of the class. Example long L;int i; extern CArchive ar; if (AR. IsStoring ()) ar<> friend carchive& operator>> (carchive& ar, cobject* pOb); throw (carchiveexception,cfileexception,cmemoryexception); Friend carchive& operator>> (carchive& ar,const cobject* pOb); throw (carchiveexception,cfileexception,cmemoryexception); Carchive&operator>> (byte& by); throw (carchiveexception,cfileexception); Carchive&operator>> (word& W); throw (carchiveexception,cfileexception); Carchive&operator>> (int& i); throw (carchiveexception,cfileexception); Carchive&operator>> (long& L); throw (carchiveexception,cfileexception); Carchive&operator>> (dword& DW); throw (carchiveexception,cfileexception); Carchive&operator>> (float& f); throw (carchiveexception,cfileexception); Carchive&operator>> (double& D); throw (carchiveexception,cfileexception); The return value allows multiple insert operators to be referenced on one line of CArchive. Describes the object or primary type that is determined by the archive file load. If used in the implementation of the classIMPLEMENT_SERIAL the macro, and then overloads the CObject extraction operator to invoke the protected ReadObject function (with a non-zero run-time pointer). This function in turn invokes the Serialize function of the class. example int i; extern CArchive ar; if (AR. IsLoading ()) ar>>i; See Carchive::readobject,cobject::serialize data member Carchive::m_pdocument description by default, set to NULL. This pointer to CDocument can be set to any situation that the Cachive instance wants to set. A common use of this pointer is to pass additional information about the serialization process to all serialized objects. When the document (CDocument derived class) is serialized, it is archived by initializing the pointer. This way, if necessary, the objects in the document can access the document. This pointer can also be used by the COleClientItem object when serialized. When you open a file or save a command, the framework sets the m_pdocument for the document that is being serialized. If you want to serialize an object linking and embedding (OLE) package container document because you are not opening the file or for saving reasons, you must explicitly set m_pdocument. For example, this should be done when serializing a package container document to a clipboard. See Cdocument,coleclientitem