# 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