Structured Storage Class for ATL & MFC

Structured storage is a useful tool in the software development. It allows us to open a single binary file and section it into several storages (which may be nested). Each storage may have one or more streams, which are used to write and retrieve the program specific information.

All this functionality is built around COM objects that MS provides with the Windows OS. We access it via IStorage and IStream interfaces and a few API function calls. This, however, is a tedious job and I decided to write a thin wrapper around these interfaces and API calls.

A Brief Example

The following code snapshot shows the class in action ...

StructuredStorage ss;
//
// Let's create a file. This also creates the root storage.
//
ss.CreateFile(L"SSTest.bin");
//
// Let's create a storage on the root one.
//
ss.CreateStorage(L"FirstLevel");
//
// Create a stream and write to it
//
CComPtr<IStream> spIStr;
ss.CreateStream(&spIStr, L"A stream");
CComBSTR bs(L"Some text to be written into the stream!");
bs.WriteToStream(spIStr);
//
// ...

Background Information

At this point I must say that the structure of the class was inspired by the article and code of Andrew Peace. His solution suited me perfectly, but unfortunately, I find it useless (for my specific case, of course) due to following reasons:

Andrew's solution uses CString and CList and is therefore bound with MFC library. We need the structured storage functionality in a COM control and therefore the linkage to MFC is not desired.
A better look at his code shows that he uses several redundant variables, which complicate the code, unnecessarily.
Sometimes (though rarely) we need to know why an interface call or a function call failed.

Although my solution eliminates the shortcomings above, it adds some new:

I am using a STL vector container. Some people try to avoid using STL containers in their COM objects.
If the solution is used inside a standard MFC project, a support for CComBSTR class is required (defined in "ATLBase.h"). Again, some people dislike this header in MFC code.
Advance features of structured storage management are still not provided.

Implementation Information

The class is build around a vector of IStorage objects. (IStorage object == storage, vector of storages == container) The first element of vector represents the root storage and subsequent elements represent sub storages. We can say that the vector of storages represents a path from the root storage to the last storage (the current one). Example:

[0] = root storage (level 0, not neceserally the root of the file).
[1] = storage inside the root (level 1).
[2] = storage inside the level 1 storage (level2)
[n] = current storage at level n (the last element of container).

If the root storage is also the root of the structured file, say "C:\test\StructFile.bin", level 1 is "Level 1", level 2 is "Level 2", ... then the path to the current storage is:

"C:\test\StructFile.bin|Level1|Level2|...|LevelN"

Vertical char | is used to emphasize the borderline between the storages. Note, that the part of the path "Level1|Level2|...|LevelN" is hidden inside the "StructFile.bin" file.

The front and the back of the vector are the most important storages. The former presents the root storage, while the later presents the current storage.

Final Remarks

Those who look into the StructuredStorage.h file, will notice a lot of commented text and funny commands. They are required by the Doxygen documentation system. It is a free documentation utility that is able to generate HTML, HTML help, LaTeX, RTF, ... documents.

I hope you will find the class useful!

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here