IStorage - Compound File Implementation

The compound file implementation of IStorage allows you to create and manage substorages and streams within a storage object residing in a compound file object. To create a compound file object and get an IStorage pointer, call the API function StgCreateDocfile. To open an existing compound file object and get its root IStorage pointer, call StgOpenStorage.

When to Use

Most applications use this implementation to to create and manage storages and streams.

Remarks

IStorage::CreateStream

Creates and opens a stream object with the specified name contained in this storage object. The OLE-provided compound file implementation of the IStorage::CreateStream method does not support the following behaviors:

The STGM_DELETEONRELEASE flag is not supported.
Transacted mode is not supported for stream objects.
Opening the same stream more than once from the same storage is not supported. The STGM_SHARE_EXCLUSIVE flag must be specified.

IStorage::OpenStream

Opens an existing stream object within in this storage object using the specified access modes specified in the grfMode parameter. The OLE-provided compound file implementation of the IStorage::OpenStream method does not support the following behavior:

The STGM_DELETEONRELEASE flag is not supported.
Transacted mode is not supported for stream objects.
Opening the same stream more than once from the same storage is not supported. The STGM_SHARE_EXCLUSIVE flag must be specified.

IStorage::CreateStorage

The OLE-provided compound file implementation of the IStorage::CreateStorage method does not support the STGM_DELETEONRELEASE flag. Specifying this flag causes the method to return STG_E_INVALIDFLAG.

IStorage::OpenStorage

Opens an existing storage object with the specified name in the specified access mode. The OLE-provided compound file implementation of the IStorage::OpenStorage method does not support the following behavior:

The STGM_PRIORITY flag is not supported for non-root storages.
Opening the same storage object more than once from the same parent storage is not supported. The STGM_SHARE_EXCLUSIVE flag must be specified.
The STGM_DELETEONRELEASE flag is not supported. If this flag is specified, the function returns STG_E_INVALIDFUNCTION.

IStorage::CopyTo

Copies only the substorages and streams of this open storage object into another storage object. The rgiidExclude parameter can be set to IID_IStream to copy only substorages, or to IID_IStorage to copy only streams.

IStorage::MoveElementTo

Copies or moves a substorage or stream from this storage object to another storage object.

IStorage::Commit

Ensures that any changes made to a storage object open in transacted mode are reflected in the parent storage; for a root storage, reflects the changes in the actual device, for example, a file on disk. For a root storage object opened in direct mode, this method has no effect except to flush all memory buffers to the disk. For non-root storage objects in direct mode, this method has no effect.

The OLE-provided compound files implementation uses a two phase commit process unless STGC_OVERWRITE is specified in the grfCommitFlags parameter. This two-phase process ensures the robustness of data in case the commit operation fails. First, all new data is written to unused space in the underlying file. If necessary, new space is allocated to the file. Once this step has been successfully completed, a table in the file is updated using a single sector write to indicate that the new data is to be used in place of the old. The old data becomes free space to be used at the next commit. Thus, the old data is available and can be restored in case an error occurs when committing changes. If STGC_OVERWRITE is specified, a single phase commit operation is used.

IStorage::Revert

Discards all changes that have been made to the storage object since the last commit.

IStorage::EnumElements

Creates and retrieves a pointer to an enumerator object that can be used to enumerate the storage and stream objects contained within this storage object.The OLE-provided compound file implementation takes a snapshot.

IStorage::DestroyElement

Removes the specified element (substorage or stream) from this storage object.

IStorage::RenameElement

Renames the specified substorage or stream in this storage object.

IStorage::SetElementTimes

Sets the modification, access, and creation times of the specified storage element. The OLE-provided compound file implementation maintains modification and change times for internal storage objects. For root storage objects, whatever is supported by the underlying file system (or ILockBytes) is supported. The compound file implementation does not maintain any time stamps for internal streams. Unsupported time stamps are reported as zero, enabling the caller to test for support.

IStorage::SetClass

Assigns the specified CLSID to this storage object.

IStorage::SetStateBits

Stores up to 32 bits of state information in this storage object. The state set by this method is for external use only. The OLE-provided compound file implementation does not perform any action based on the state.

IStorage::Stat

Retrieves the STATSTG structure for this open storage object.