Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This method ensures that any changes made to a storage object open in transacted mode are reflected in the parent storage.

For a root storage, this method reflects the changes in the actual device, for example, a file on disk.

For a root storage object opened in direct mode, this method has no effect except to flush all memory buffers to the disk.

For nonroot storage objects in direct mode, this method has no effect.

Syntax 

HRESULT Commit( 
  DWORD 
grfCommitFlags 
);

Parameters

grfCommitFlags

[in] Value that controls how the changes are committed to the storage object. For a definition of these values, see the STGCenumeration.

Return Value

The following table shows the return values for this method.

Value Description

S_OK

Changes to the storage object were successfully committed to the parent level.

If STGC_CONSOLIDATE was specified, the storage was successfully consolidated, or the storage was already too compact to consolidate further.

STG_S_MULTIPLEOPENS

The commit operation succeeded, but the storage could not be consolidated because it had been opened multiple times using the STGM_NOSNAPSHOT flag.

STG_S_CANNOTCONSOLIDATE

The commit operation succeeded, but the storage could not be consolidated due to an incorrect storage mode.

For compound files, the storage may have been opened using the STGM_NOSCRATCH flag, or the storage may not be the outermost transacted level.

STG_S_CONSOLIDATIONFAILED

The commit operation succeeded, but the storage could not be consolidated due to an internal error.

For example, storage could not be consolidated if there is a memory allocation failure.

E_PENDING

Asynchronous storage only: Part or all of the data to be committed is currently unavailable.

For more information, see the IFillLockBytesinterface and Asynchronous Storage.

STG_E_INVALIDFLAG

The value for the grfCommitFlagsparameter is not valid.

STG_E_INVALIDPARAMETER

One of the parameters was not valid.

STG_E_NOTCURRENT

Another open instance of the storage object has committed changes. As a result, the current commit operation may overwrite previous changes.

STG_E_MEDIUMFULL

No space left on device to commit.

STG_E_TOOMANYOPENFILES

The commit operation could not be completed because there are too many open files.

STG_E_REVERTED

The storage object has been invalidated by a revert operation above it in the transaction tree.

Remarks

IStorage::Commitmakes permanent changes to a storage object that is in transacted mode, in which changes are accumulated in a buffer, and not reflected in the storage object until there is a call to this method.

The alternative is to open an object in direct mode, in which changes are immediately reflected in the storage object and therefore does not require a commit operation.

Calling this method on a storage opened in direct mode has no effect, unless it is a root storage, in which case it ensures that changes in memory buffers are written to the underlying storage device.

The commit operation publishes the current changes in this storage object and its children to the next level up in the storage hierarchy.

To undo current changes before committing them, call the IStorage::Revertmethod to roll back to the last-committed version.

Calling IStorage::Commithas no effect on currently-opened nested elements of this storage object. They are still valid and can be used. However, the IStorage::Commitmethod does not automatically commit changes to these nested elements.

The commit operation publishes only known changes to the next higher level of the storage hierarchy. Therefore, transactions to nested levels must be committed to this storage object before they can be committed to higher levels.

In commit operations, you need to take steps to ensure that data is protected during the commit process:

  • When committing changes to root storage objects, the caller must check the return value to determine whether the operation has been completed successfully, and if not, that the old committed contents of the IStorageinterface are still intact and can be restored.

  • If this storage object was opened with some of its items excluded, then the caller is responsible for rewriting them before calling commit. Write mode is required on the storage opening for the commit to succeed.

  • Unless prohibiting multiple simultaneous writers on the same storage object, an application calling this method should specify at least STGC_ONLYIFCURRENT in the grfCommitFlagsparameter to prevent the changes made by one writer from inadvertently overwriting the changes made by another.

If the STGC_CONSOLIDATE flag is not supported by a storage implementation, then calling IStorage::Commitwith STGC_CONSOLIDATE specified in the grfCommitFlagsparameterreturns the value STG_E_INVALIDFLAG.

To determine whether the platform supports this interface, see Determining Supported COM APIs.

Requirements

Header objidl.h, objidl.idl
Library ole32.lib, uuid.lib
Windows Embedded CE Windows CE 2.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also