Storage and stream objects support access modes like those found with traditional handle-based files. These modes, used with any function that creates or opens a storage or a stream, are defined with flags beginning with STGM_*, as shown in Table 7-3. Many of these access modes match exactly the OF_* flags used with the Windows API function OpenFile and, in fact, share the same integer values. As with OpenFile, you can combine any of these flags with a bitwise OR operation, producing the same effects that OpenFile has on a traditional file. Beyond that, moreover, OLE offers additional flags with special functions that are not available elsewhere, as described in Table 7-4 on the following page.
Structured Storage Flag | Definition Using OpenFile Flags |
STGM_READ (default) | OF_READ |
STGM_WRITE | OF_WRITE |
STGM_READWRITE | OF_READWRITE |
STGM_SHARE_DENYNONE | OF_SHARE_DENY_NONE |
STGM_SHARE_DENYREAD | OF_SHARE_DENY_READ |
STGM_SHARE_DENYWRITE | OF_SHARE_DENY_WRITE |
STGM_SHARE_EXCLUSIVE | OF_SHARE_EXCLUSIVE |
STGM_CREATE | OF_CREATE |
Table 7-3.
Basic available access modes and their Windows API OpenFile equivalents.
Structured Storage Flag | Description |
STGM_DIRECT (default) | Opens the element for direct access. |
STGM_TRANSACTED | Opens the element so that changes are buffered and not saved until the element is committed. |
STGM_FAILIFTHERE (default) | Fails to create an element of a given name if one having that name already exists. |
STGM_CONVERT (storages only) | Allows an application to convert any traditional file to a storage that contains a single stream named "CONTENTS"; this stream contains exactly the same data as the original file. If the file is opened with STGM_DIRECT, the old file is immediately and permanently converted on disk, and therefore STGM_CONVERT always requires STGM_WRITE. To prevent permanent conversion, use STGM_TRANSACTED. |
STGM_DELETEONRELEASE | Deletes the file underneath a root storage when the object is destroyed through Release. This flag is highly useful for temporary files. |
STGM_PRIORITY | Allows an application to open a direct, read-only storage or stream for a short time to quickly read some data. This flag tells the storage implementation to internally avoid extra buffering and processing, making the operation much faster. For more information, see the OLE Programmer's Reference. |
Table 7-4.
Additional Structured Storage flags.
When using these flags, remember that a stream is always restricted by the access mode of its parent storage. If the storage is read-only, streams within that storage are also read-only. Transactioning, however, is not a limitation—you can have direct streams inside a transacted storage. From the stream's point of view, changes are permanent, but from the view of the whole storage, that stream is transactioned in the scope of its parent storage.
Be aware that Structured Storage offers a finer granularity of file sharing than traditional files can provide. Multiple applications (run by multiple end users) can easily open different elements within the same storage hierarchy using exclusive access. They can even open the same element as long as STGM_SHARE_EXCLUSIVE is not specified.2 In such a case, transactioning allows each application to know whether another application has already changed the contents of that element since it was opened.
2 At the time of writing only the root storage object can be opened with flags other than STGM_SHARE_EXCLUSIVE. Using other flags to open down-level elements will fail with STG_E_INVALIDFLAG. |