Edit

Two Ways to Create a CArchive Object

  • Article

There are two ways to create a CArchive object:

Implicit Creation of a CArchive Object via the Framework

The most common, and easiest, way is to let the framework create a CArchive object for your document on behalf of the Save, Save As, and Open commands on the File menu.

Here is what the framework does when the user of your application issues the Save As command from the File menu:

  1. Presents the Save As dialog box and gets the filename from the user.

  2. Opens the file named by the user as a CFile object.

  3. Creates a CArchive object that points to this CFile object. In creating the CArchive object, the framework sets the mode to "store" (write, serialize), as opposed to "load" (read, deserialize).

  4. Calls the Serialize function defined in your CDocument-derived class, passing it a reference to the CArchive object.

Your document's Serialize function then writes data to the CArchive object, as explained shortly. Upon return from your Serialize function, the framework destroys the CArchive object and then the CFile object.

Thus, if you let the framework create the CArchive object for your document, all you have to do is implement the document's Serialize function that writes and reads to and from the archive. You also have to implement Serialize for any CObject-derived objects that the document's Serialize function in turn serializes directly or indirectly.

Explicit Creation of a CArchive Object

Besides serializing a document via the framework, there are other occasions when you may need a CArchive object. For example, you might want to serialize data to and from the Clipboard, represented by a CSharedFile object. Or, you may want to use a user interface for saving a file that is different from the one offered by the framework. In this case, you can explicitly create a CArchive object. You do this the same way the framework does, using the following procedure.

To explicitly create a CArchive object

  1. Construct a CFile object or an object derived from CFile.

  2. Pass the CFile object to the constructor for CArchive, as shown in the following example:

    CFile theFile;
theFile.Open(_T("CArchive__Test.txt"), CFile::modeCreate | CFile::modeWrite);
CArchive archive(&theFile, CArchive::store);

    The second argument to the CArchive constructor is an enumerated value that specifies whether the archive will be used for storing or loading data to or from the file. The Serialize function of an object checks this state by calling the IsStoring function for the archive object.

When you are finished storing or loading data to or from the CArchive object, close it. Although the CArchive (and CFile) objects will automatically close the archive (and file), it is good practice to explicitly do so since it makes recovery from errors easier. For more information about error handling, see the article Exceptions: Catching and Deleting Exceptions.

To close the CArchive object

  1. The following example illustrates how to close the CArchive object:

    archive.Close();
theFile.Close();

See also

Serialization: Serializing an Object