STGC

The STGC enumeration constants specify the conditions for performing the commit operation in the IStorage::Commit and IStream::Commit methods.

typedef enum tagSTGC 
{ 
    STGC_DEFAULT                               = 0, 
    STGC_OVERWRITE                             = 1, 
    STGC_ONLYIFCURRENT                         = 2, 
    STGC_DANGEROUSLYCOMMITMERELYTODISKCACHE    = 4 
    STGC_CONSOLIDATE                           = 8 
} STGC; 
 

Elements

STGC_DEFAULT

You can specify this condition with STGC_CONSOLIDATE, or some combination of the other three flags. You would use this value mainly to make your code more readable.

STGC_OVERWRITE

The commit operation can overwrite existing data to reduce overall space requirements. This value is not recommended for typical usage because it is not as robust as the default case. In this case, it is possible for the commit to fail after the old data is overwritten but before the new data is completely committed. Then, neither the old version nor the new version of the storage object will be intact.

You can use this value in cases where:

• The user has indicated a willingness to risk losing the data
• The low memory save sequence will be used to safely save the storage object to a smaller file
• A previous commit returned STG_E_MEDIUMFULL but overwriting the existing data would provide enough space to commit changes to the storage object

Note that the commit operation checks for adequate space before any overwriting occurs. Thus, even with this value specified, if the commit operation fails due to space requirements, the old data will remain safe. The case where data loss can occur is when the commit operation fails due to some reason other than lack of space and the STGC_OVERWRITE value was specified.

STGC_ONLYIFCURRENT

Prevents multiple users of a storage object from overwriting one another's changes. The commit operation occurs only if there have been no changes to the saved storage object since the user most recently opened it. Thus, the saved version of the storage object is the same version that the user has been editing. If other users have changed the storage object, the commit operation fails and returns the STG_E_NOTCURRENT value. You can override this behavior by calling the IStorage::Commit or IStream::Commit method again using the STGC_DEFAULT value.

STGC_DANGEROUSLYCOMMITMERELYTODISKCACHE

Commits the changes to a write-behind disk cache, but does not save the cache to the disk. In a write-behind disk cache, the operation that writes to disk actually writes to a disk cache, thus increasing performance. The cache is eventually written to the disk, but usually not until after the write operation has already returned. The performance increase comes at the expense of an increased risk of losing data if a problem occurs before the cache is saved and the data in the cache is lost.

If you do not specify this value, then committing changes to root-level storage objects is robust even if a disk cache is used. The two-phase commit process ensures that data is stored on the disk and not just to the disk cache.

STGC_CONSOLIDATE

Indicates that a storage should be consolidated after it is committed resulting in a smaller file on disk. This flag is valid only on the outermost storage object opened in transacted mode. It is not valid for streams. The STGC_CONSOLIDATE flag can be combined with any other STGC flags.

Remarks

You can specify STGC_DEFAULT or some combination of STGC_OVERWRITE, STGC_ONLYIFCURRENT, and STGC_DANGEROUSLYCOMMITMERELYTODISKCACHE for normal commit operations. Specify STGC_CONSOLIDATE with any other STGC flags.

Typically, you would use STGC_ONLYIFCURRENT to protect the storage object in cases where more than one user can edit the object simultaneously.

For native structured storage (NSS), it is unnecessary to consolidate storage files. NSS uses NTFS support for multiple data streams in a file, which automatically manages unused space in the streams.

QuickInfo

  Windows NT: Use version 3.1 and later.
  Windows: Use Windows 95 and later.
  Windows CE: Unsupported.
  Header: Declared in wtypes.h.

See Also

IPropertyStorage, IStorage, IStream