STGM

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This enumeration contains values used in the storage and stream interfaces to indicate the conditions for creating and deleting the object and access modes for the object.

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

Elements

• 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.

  To ignore the changes, call the Revert method in the IStream, IStorage, or IPropertyStorage interfaces.

  The COM compound file and NSS implementations of IStorage do 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.

  The compound file, NSS standalone, and NTFS implementations of IPropertySetStorage similarly do not support transacted, simple mode property sets as these property sets are stored in streams.

  However, non-simple property sets, which can be created by specifying the PROPSETFLAG_NONSIMPLE flag in the grfFlags parameter of IPropertySetStorage::Create, are 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_DIRECT_SWMR
  The STGM_DIRECT_SWMR supports direct mode for single-writer, multi-reader file operations.

• 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_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
  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
  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
  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 the following 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
  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 cannot 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 the following flags.

STGM_CREATE | STGM_READWRITE | STGM_SHARE_EXCLUSIVE 

The STGM_DIRECT flag can be combined with one of the following flags:

• STGM_READ | STGM_SHARE_DENY_WRITE
• STGM_READWRITE | STGM_SHARE_EXCLUSIVE
• STGM_READ | STGM_PRIORITY

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

With single-writer, multi-reader, direct mode, the following flag combinations are valid:

STGM_DIRECT_SWMR | STGM_READWRITE | STGM_SHARE_DENY_WRITE

and

STGM_DIRECT_SWMR | STGM_READ | STGM_SHARE_DENY_NONE

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

• There is no support for substorages.
• 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.
• The storage and stream objects cannot be marshaled.
• 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.
• 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.

Requirements

See Also

Reference

ISequentialStream::Read
IStorage
IStream
StgCreateDocfileOnILockBytes
StgOpenStorage