STGM

The STGM enumeration values are used in the storage and stream interfaces to indicate the conditions for creating and deleting the object and access modes for the object.

The STGM values are used in the IStorage and IStream interfaces, and in the StgCreateDocfile and StgCreateDocfileOnILockBytes functions to indicate the conditions for creating and deleting the object and access modes for the object.

STGM values are as follows:

STGM_DIRECT 0x00000000L
STGM_TRANSACTED 0x00010000L
STGM_SIMPLE 0x08000000L
STGM_READ 0x00000000L
STGM_WRITE 0x00000001L
STGM_READWRITE 0x00000002L
STGM_SHARE_DENY_NONE 0x00000040L
STGM_SHARE_DENY_READ 0x00000030L
STGM_SHARE_DENY_WRITE 0x00000020L
STGM_SHARE_EXCLUSIVE 0x00000010L
STGM_PRIORITY 0x00040000L
STGM_DELETEONRELEASE 0x04000000L
STGM_CREATE 0x00001000L
STGM_CONVERT 0x00020000L
STGM_FAILIFTHERE 0x00000000L
STGM_NOSCRATCH 0x00100000L
STGM_NOSNAPSHOT 0x00200000L

Elements

STGM_DIRECT. STGM_TRANSACTED, STGM_SIMPLE group:
STGM_DIRECT
In direct mode, each change to a storage element is written as it occurs. This is the default.
STGM_TRANSACTED
In transacted mode, changes are buffered and are written only if an explicit commit operation is called. The changes can be ignored by calling the Revert method in the IStream or IStorage interfaces. The COM compound file implementation does not support transacted streams, which means that streams can be opened only in direct mode, and you cannot revert changes to them. Transacted storages are, however, supported.
STGM_SIMPLE
STGM_SIMPLE is a mode that provides a much faster implementation of a compound file in a limited, but frequently used case. It is described in detail in the following Remarks section.
STGM_READ, STGM_WRITE, STGM_READWRITE group:
STGM_READ
For stream objects, STGM_READ allows you to call the ISequentialStream::Read method. For storage objects, you can enumerate the storage elements and open them for reading.
STGM_WRITE
STGM_WRITE lets you save changes to the object.
STGM_READWRITE
STGM_READWRITE is the combination of STGM_READ and STGM_WRITE.
STGM_SHARE_* group:
STGM_SHARE_DENY_NONE
Specifies that subsequent openings of the object are not denied read or write access.
STGM_SHARE_DENY_READ
Prevents others from subsequently opening the object in STGM_READ mode. It is typically used on a root storage object.
STGM_SHARE_DENY_WRITE
Prevents others from subsequently opening the object in STGM_WRITE mode. This value is typically used to prevent unnecessary copies made of an object opened by multiple users. If this value is not specified, a snapshot is made, independent of whether there are subsequent opens or not. Thus, you can improve performance by specifying this value.
STGM_SHARE_EXCLUSIVE
The combination of STGM_SHARE_DENY_READ and STGM_SHARE_DENY_WRITE.
STGM_PRIORITY
STGM_PRIORITY
Opens the storage object with exclusive access to the most recently committed version. Thus, other users cannot commit changes to the object while you have it open in priority mode. You gain performance benefits for copy operations, but you prevent others from committing changes. So, you should limit the time you keep objects open in priority mode. You must specify STGM_DIRECT and STGM_READ with priority mode.
STGM_DELETEONRELEASE
STGM_DELETEONRELEASE
Indicates that the underlying file is to be automatically destroyed when the root storage object is released. This capability is most useful for creating temporary files.
STGM_CREATE, STGM_CONVERT, STGM_FAILIFTHERE Group
STGM_CREATE
Indicates that an existing storage object or stream should be removed before the new one replaces it. A new object is created when this flag is specified, only if the existing object has been successfully removed.

This flag is used in three situations:

STGM_CONVERT
Creates the new object while preserving existing data in a stream named CONTENTS. In the case of a storage object or a byte array, the old data is flattened to a stream regardless of whether the existing file or byte array currently contains a layered storage object.
STGM_FAILIFTHERE
Causes the create operation to fail if an existing object with the specified name exists. In this case, STG_E_FILEALREADYEXISTS is returned. STGM_FAILIFTHERE applies to both storage objects and streams.
STGM_NOSCRATCH
Windows95 only: In transacted mode, a scratch file is usually used to save until the commit operation. Specifying STGM_NOSCRATCH permits the unused portion of the original file to be used as scratch space. This does not affect the data in the original file, and is a much more efficient use of memory.
STGM_NOSNAPSHOT
This flag is used when opening a storage with STGM_TRANSACTED and without STGM_SHARE_EXCLUSIVE or STGM_SHARE_DENY_WRITE. In this case, specifying STGM_NOSNAPSHOT prevents the system-provided implementation from creating a snapshot copy of the file. Instead, changes to the file are written to the end of the file. Unused space is not reclaimed unless consolidation is done during the commit, and there is only one current writer on the file. When the file is opened in no snapshot mode, another open cannot be done without specifying STGM_NOSNAPSHOT - in other words, you can't combine no-snapshot with other modes.

Remarks

You can combine these flags but you can only choose one flag from each group of related flags. Groups are indicated under the headings in the previous section.

The STGM_SIMPLE flag is applicable only when combined with:

STGM_CREATE | STGM_READWRITE | STGM_SHARE_EXCLUSIVE 
 

Note that direct mode is implied by the absence of STGM_TRANSACTED.

This mode is useful for applications that perform complete save operations. It has the following constraints:

  1. There is no support for substorages.
  2. Access to streams follows a linear pattern. Once a stream is released, that stream cannot be opened for read/write operations again. The IStorage::OpenStream method is not supported in this implementation.
  3. The storage and stream objects cannot be marshaled.
  4. Each stream is at least 4096 bytes in length. If fewer than 4096 bytes are written into a stream by the time the stream is released, the stream will be extended to contain 4096 bytes.
  5. In this compound file implementation, only a subset of the methods of IStorage and IStream are available.

Specifically, in simple mode, supported IStorage methods are QueryInterface, AddRef, Release, CreateStream, Commit, and SetClass. In addition, SetElementTimes is supported with a NULL name, allowing applications to set times on a root storage in simple mode.

Supported IStream methods are QueryInterface, AddRef, Release, Seek, and SetSize. Also, Read and Write methods on ISequentialStream are supported.

All the other methods of IStorage and IStream return STG_E_INVALIDFUNCTION.

File optimization modes such as STGM_SIMPLE, STGM_NOSCRATCH, and STGM_NOSNAPSHOT are not supported for NTFS native structured storage files. When storing storage objects on NTFS systems in native file format, the files are automatically converted to regular file format for all non-NT and FAT partitions.

QuickInfo

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

See Also

StgCreateDocfile, ISequentialStream::Read, IStorage, StgCreateDocfileOnILockBytes, StgOpenStorage, StgOpenStorageOnILockBytes