IStorage::Commit

Ensures that any changes made to a storage object open in transacted mode are reflected in the parent storage. If the storage object is the root storage, the IStorage::Commit method reflects the changes in the actual device, for example, a file on disk. If the storage object is the root storage and is open in direct mode, this method has no effect except for flushing all memory buffers to the disk. For non-root storage objects in direct mode, this method has no effect.

HRESULT Commit(

DWORD grfCommitFlags	//Specifies how changes are to be committed
);

Parameter
grfCommitFlags

[in]Controls how the changes are committed to the storage object. See the STGC enumeration for a definition of these values.

Return Values
S_OK

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

STG_E_INVALIDFLAG

The value for the grfCommitFlags parameter 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. Thus, 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.

Comments
Storage objects can be opened in direct or transacted mode. In direct mode, changes are immediately reflected in the storage object. In transacted mode, changes are accumulated and are not reflected in the storage object until an explicit commit operation is done. The commit operation publishes the currently known changes in this storage object and its children to the next higher level in the storage hierarchy. Transacted mode allows an efficient way to revert to a previous version undoing changes prior to the commit operation.

Changes that have been made to this storage object since it was opened or since the last commit operation are reflected in the storage object. The changes are published to the next level of the storage hierarchy. If the parent is opened in transacted mode, the parent may still revert at a later time, rolling back the changes to this storage object.

Calling IStorage::Commit has no effect on currently-opened nested elements of this storage object. They are still valid and can be used. However, the IStorage::Commit method 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. Thus, transactions to nested levels must be committed to this storage object before they can be committed to higher levels.

For storage objects opened in direct mode, the commit operation does nothing except in the case of a root storage object. In this case, the commit operation is similar to a flush buffer operation ensuring that changes in memory buffers are written to the underlying storage device.

In commit operations, steps must be taken to ensure the robustness of data during the commit process:

When committing changes to root storage objects, the caller must take care to ensure that the operation successfully completes or that, when failing, the old committed contents of the IStorage 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 they prohibit multiple simultaneous writers on the same storage object, applications will usually want to specify at least STGC_ONLYIFCURRENT in the grfCommitFlags parameter to prevent the changes made by one writer from inadvertently overwriting the changes made by another.

Note to Callers
The OLE-provided compound files use a two phase commit process unless STGC_OVERWRITE is specified in the grfCommitFlags parameter. This two-phase process ensures the robustness of data in case the commit operation fails. First, all new data is written to unused space in the underlying file. If necessary, new space is allocated to the file. Once this step has been successfully completed, a table in the file is updated using a single sector write to indicate that the new data is to be used in place of the old. The old data becomes free space to be used at the next commit. Thus, the old data is available and can be restored in case an error occurs when committing changes. If STGC_OVERWRITE is specified, a single phase commit operation is used.