Complex Compound Files: Patron

English grammar defines a number of sentence structures. A simple sentence expresses one idea, such as "The rabbit sat in its form."4 Compound sentences express more than one independent idea, such as "The rabbit sat in its form, and the photographer set up her camera." These sentences have a vague notion of concurrency but no hard evidence of it. A complex sentence, however, defines such a relationship, as in "The rabbit sat in its form while the photographer set up her camera." A complex compound sentence is more on the order of "Although the rabbit felt trepidation about most humans, it calmly sat in its form, and the photographer continued to set up her camera."

The idea of a single flat traditional file is an analog of the simple sentence structure. A compound file, one with a single storage and a single stream, is much like a compound sentence: two elements that are related by being in the same place at the same time. When we add more streams in the root storage, we make things more complex—the meaning of the data in one stream might be partially or completely defined by the context of the data in another stream. As we use even more complex structures, we add substorages alongside these streams and new streams under those substorages. We can build any complexity we want, and thus we can call such structures complex compound files.

For this chapter's version of Patron (CHAP07\PATRON), we'll implement the storage structure shown in Figure 7-8, which is the same as that shown in Figure 7-6 on page 353, but without the page header streams or tenant storages because we haven't yet added the capability of creating tenants. Each Patron file is a root storage, underneath which live two streams. The first contains the printer configuration; the second contains the list of pages within the document, including the number of pages, the current page (the one to view when opening the file), and any number of page identifiers. Each page is assigned a unique DWORD according to the order of creation, and the page list stream contains the next ID to use. The ordering of pages in the document is determined by the sequence of IDs in the page list, not by the ID values themselves, because the fourth page created might have been inserted at the beginning of the document. Each page is given its own substorage under the root; the substorage name is Page <ID>, where <ID> is the ASCII representation of the identifier. For this chapter, these substorages will not contain anything else—they do, however, provide the structure in which we can create tenants later on.

Figure 7-8.

Exact layout of Patron's compound files as described in this chapter, prior to adding tenant support.

Adding file I/O capabilities using compound files requires considerable modifications and additions to Patron: filling out its CPatronDoc members Load and Save (DOCUMENT.CPP), adding structural support in the CPages class (PAGES.CPP), and adding functionality to the CPage class (PAGE.CPP). All the code is available on the companion CD and need not be shown here. For the most part, Patron follows the same sorts of call sequences for saving and loading files that were described for Cosmo earlier in this chapter, except that not everything happens at the same time and in the same place. Patron's file handling is summarized as follows:

• CPatronDoc::Load either opens an existing file (StgOpenStorage) or creates a temporary file (using StgCreateDocfile with a NULL filename). It passes the resulting IStorage pointer to CPages::StorageSet, which uses the pointer when creating or opening the page substorages.
• CPages::StorageSet reads the Page List stream in the storage given to it and creates all the necessary pages described by that stream. (This is more efficient than calling IStorage::EnumElements to find all the page names directly. The information in the stream is sufficient to re-create those names more quickly.) If this is a new file, StorageSet creates the "Page List" stream, setting the next ID counter to 0. This function then creates or reads the device configuration stream, switches to the current page, and returns. When a repaint occurs, the user will see the current page.
• CPatronDoc::Save, when performing a simple Save operation, tells each page to update its storages by calling CPages::StorageUpdate, followed by a call to IStorage::Commit(STGC_DEFAULT). If performing a Save As operation, CPatronDoc::Save creates a new compound file, updates all the page storages, calls CopyTo to store all the information in the new file, and then calls Commit to make it all permanent. If CopyTo fails due to lack of memory, Patron queries for IRootStorage and calls IRootStorage::SwitchToFile followed by IStorage::Commit. In either case, the new file is saved properly.
• CPages::StorageUpdate calls CPage::Update for the current page, closes that page, and rewrites the "Page List" stream. This function needs only to update the current page: when the user switches to another page, Patron ends up in CPages::CurPageSet, calling CPage::Close, which tells the page to commit its changes. That page's substorage then contains the current copy of its information, so we can release that substorage and open the new page to view. In other words, changing pages commits the previous one and opens the new one, so when we save the entire file we need only commit the changes to the current page. In this manner, Patron performs the necessary commits on each level of its storage, which we'll expand in a later chapter when adding tenants.
• The functions CPatronDoc::Print and CPatronDoc::PrinterSetup, along with CPages::DevModeSet, CPages::DevModeGet, CPages::ConfigureForDevice, and CPages::Print—all of which you can find in PRINT.CPP—manage the printer information inside the "device configuration" stream. This is an example of keeping an infrequently used data structure in a stream at all times instead of loading it into memory. The only drawbacks are that Patron ties a document to a specific printer device and that the DEVMODE structure it stores in this stream is not portable between platforms. Both design decisions would be silly in a shipping software product, but I use DEVMODE here as a matter of convenience for this sample, whose fundamental purpose is not sales but demonstration of concepts.5
• Deleting a page calls CPages::DeletePage, which calls CPage::Destroy. This in turn calls IStorage::DestroyElement to delete its own substorage. (Remember that the CPage class is a run-time C++ object in memory, which is here destroying its own substorage in the compound file. This is not a case of the object destroying itself, only its storage.)

I encourage you to follow through the code and see where each piece of Patron's architecture (I don't call it ideal by any means) works with its piece of the storage hierarchy. The CPatronDoc and CPages classes both work with the root storage, whereas instances of CPage work with their own substorage. Let's look at two of the more interesting parts of this implementation.