Introduction
Did you ever want to group a bunch of files together into a single file for run-time read/write access but didn’t want to bother with a file format structure for accessing the files? There are many uses for this technology such as revision/undo storing, dynamic access to resources, incremental updates, WAD files etc. Microsoft’s answer to implementing these types of solutions is to use a technology known as Compound Files (CF). Note that Compound files are an implementation of the ActiveX structured storage model (From MSDN article, "Containers: Compound Files)
CFs may be viewed as a file system within a file. They allow you to create files (known as streams) and directories (known as sub-storages) within a single file. Compound files offer some advantages of a database (such as transactions with rollback) and general file system functionality. Files within the CF may be read/written from/to incrementally just as they are within a normal filesystem.
The Problem
Application programming to access a CF usually requires quite a bit of manipulations of the IStorage and IStream interfaces that are daunting to many. In addition, management of the interfaces at the right time can cause problems if not handled correctly.
Solutions
What is needed is another model for accessing streams and sub-storages within a CF. A very simple model that every application programmer is familiar with the concept of files. Using MFC, they are managed by the CFile class. Using this model, we can extend the class to accommodate the CFs.
This project presents the following solutions.
- An MFC CFile derived class (CStgFile) that allow simple CFile type access to a stream within a file.
- Methods for creation of CFs (CreateStg()) and the creation of single level sub-storages (MkStg()).
- An OLE Automation (COM) class ("gstg.core") for manipulating CFs from scripting languages (and/or a CDispatch derived MFC class).
- JavaScript examples of copying files in/out of a CF.
In addition, there is additional code to provide the following external file-system support.
- An MFC class (CScanDir) that is used to scan a file-system directory for a file specification and return the results in a string array. Support for overriding the default behavior is also provided.
- An OLE Automation (COM) class ("gstg.dir" ) for accessing directory information from scripting languages (and/or a CDispatch derived MFC class).
- JavaScript examples of scanning a directory for files and sub-directories.
And finally, an example to demonstrate the functionality:
- Copy a sub-directory of files from a file system into a sub-storage in a CF.
Development Methodology
- The core code (CStgFile, CScanDir) is first developed as reusable MFC classes.
- They are then "wrapped" with an OLE Automation (COM) layer that may be used by OLE Automation scripting engines (VB, VBA, WSH, etc.) and/or other MFC application via a CDispatch derived interface (using the TLB).
- Finally, JavaScript test scripts are developed for exercising the basic functionality of the code before integration to a more thorough test.
Limitations
To reduce the complexities of illustrating these concepts, the following limitations were imposed.
- CFs do not use TRANSACTED file semantics. All accesses are DIRECT.
- CF implementation limited to one level of sub-storages.
- Very little error (return codes) checking is performed in the OLE Automation wrappers.
- Methods are not "friendly" to errant programming practices.
Examples of Usage
MFC Example
To illustrate how simple it is to use the CStgFile MFC class for copying an external file to a newly created CF, the following MFC code may be used.
CFile File( "tmp.tmp", CFile::modeRead ); // open a source file
CStgFile FileStg; // instance the CF wrapperFileStg.CreateStg( "tmp.stg" ); // creates the storage
FileStg.Open( "tmp.tmp", CFile::modeCreate | CFile::modeWrite);while( 1 ) // copy all bytes to stream
{
UINT cB = 0;
BYTE rgB[512*8];
while( (cB = FileSrc.Read( rgB, sizeof(rgB) )) > 0 )
{
FileStg.Write( rgB, cB );
}
}FileStg.Close(); // close the stream
FileStg.CloseStg(); // close the CF file
Notice in this example, the one call to CreateStg() converts accesses to the file to using a CF. If this call is omitted, the access to the object uses the normal CFile methods. This may be useful in debugging when you wish to access the streams as normal files.
JavaScript Example
To perform the same operation in JavaScript, the solution is even simpler:
var objStg = WScript.CreateObject( "gstg.core" ); // create object
objStg.Create( "tmp.stg" ); // create the CF
objStg.CopyTo( "tmp.tmp", "tmp.tmp" ); // copy the external file
objStg.Close(); // close the CF
Other Examples
Other script examples are in the scr, scr/stg and scr/dir sub-directories. These include an example to copy a whole directory of files from the file system into a sub-storage of a CF (cp_bmps.js).
Conclusion
Using Compound Files becomes much easier using the CStgFile class for accessing streams and sub-storages. There are many other uses and advantages of using Compound Files that are beyond the scope of this document. Please refer to MSDN for further reading about OLE Compound Files.
Notes
- In order to run-the OLE Automation examples, you must register the DLL[s].
- In order to run the JavaScript example, you must use the Window Scripting Host CScript application. This is available for download from Microsoft and comes with Window98.
- Use the DFView application from Microsoft to view CFs created with the CStgFile class.
- These classes were developed with MS Visual C++ V5.0 and should be compatible with previous releases of the compiler.
- There are some characters that are considered invalid for stream names (e.g. '!').
Other Uses
After understanding how CFs store streams of data, other uses become apparent:
- A Web-Site in a file.
- Resources for localization.
- BLOB type storage insertion/retrieval without the database overhead.
- Archival of data with direct access.
- Etc.
Future
The class for accessing streams within a CF should be extended to support N levels of organization. In addition, support for selecting TRANSACTIONs should be included.
Date Posted: November 20, 1998
