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

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 OLE 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 IStream::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:

  • when you are trying to create a storage object on disk but a file of that name already exists

  • when you are trying to create a stream inside a storage object but a stream with the specified name already exists

  • when you are creating a byte array object but one with the specified name already exists
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.

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, Write, Seek, SetSize, and Read.

All the other methods of IStorage and IStream return STG_E_INVALIDFUNCTION.

See Also

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