STGM

  • Article

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

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
STGM_DIRECT_SWMR 0x00400000L

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

Runs on Versions Defined in Include Link to
Windows CE OS        

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

ISequentialStream::Read,IStorage, IStream, StgCreateDocfileOnILockBytes, StgOpenStorage

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.