Structured Storage - The DocFile

• Download demo project - 17 Kb
• Download source files - 3 Kb

Introduction

Structured storage is something which, when done using the plain Windows API, seems overly complicated; much more so than is needed. The aim of this article is to briefly introduce you to the concepts behind structured storage, and then provide a helper class to simplify its usage.

The idea behind structured storage is that a single file can itself contain a basic filing system. Its main reason for existence was to help with OLE documents: embedded objects are simply save as separate 'streams' within the single file. Here is a diagram which illustrates this concept:

Although this technology is primarily for use in OLE, it can be put to other uses. In order to help you access the functionality of this powerful tool easily, I have created a helper class, namely CSSFile, to aid in the creation, and modification of structured storage files.

Updates

If you have used this class previously, you will most likely wish to update your code to use the latest version. Here are the main differences (note that the interface remains the same):

• The use of const references for faster parameter passing
• Quicker operation as a result of reduced 'waste' code
• Removal of un-needed variables and code from the class
• Better arrangement of source and header files.
• Integration of help into the article rather than as a HTML Help download.
• Proper UNICODE awareness

Usage of the class

Whilst the class is fairly straightforward, I have listed the functions and their interfaces below to aid your usage of the class:

Function: CreateSSFile(...)

Parameters

filename - the name of the file to be created

mode - the mode of access for the file

Return value

'true' if the file was successfully created

Function: OpenSSFile(...)

Parameters

filename - the name of the file to open

mode - the mode of access for the file

Return value

'true' if the file was successfully opened

Function: Attach(...)

Parameters

pNews - the storage this object should hook

Return value

The previous storage being managed by the object

Function: Detach(...)

No Parameters

Return value

The previous storage being managed by the object

Function: Close()

No Parameters

No Return value

Function: CreateStorage(...)

Parameters

name - the name of the storage to create (will be created within the current path inside the root storage)

enter - enter the storage after creation?

mode - the mode of access for the storage

Return value

'true' if the storage was successfully created

Function: EnterStorage(...)

Parameters

name - the name of the storage to open

mode - the mode of access for the storage

Return value

'true' if the storage was successfully opened

Function: ExitStorage(...)

No Parameters

Return value

'true' if the storage path was moved up a level

Function: CreateStream(...)

Parameters

name - the name of the stream to create

sf - a COleStreamFile into which the stream is opened

mode - the mode of access for the stream

Return value

'true' if the stream was successfully created

Function: OpenStream(...)

Parameters

name - the name of the stream to open

sf - a COleStreamFile into which the stream is opened

mode - the mode of access for the stream

Return value

'true' if the stream was successfully opened

Function: DestroyElement(...)

Parameters

name - the name of the element to destroy

Return value

'true' if the element was successfully destroyed

Function: GetRootStorage()

No Parameters

Return value

The root of the currently open storage

Function: GetCurrentStorage()

No Parameters

Return value

The currently open storage

Function: IsOpen()

No Parameters

Return value

Whether a file is currently being managed by the object

Function: GetFilename()

No Parameters

Return value

The filename of the root storage

Function: GetPath(...)

Parameters

SepChar - the character to be used to separate the paths in the storages (i.e. Windows uses '\' for standard file system paths).

Return value

The current path within the storage (including the filename of the root storage).