IStorage::Commit 方法 (objidl.h)

Commit 方法可确保对以事务处理模式打开的存储对象所做的任何更改都反映在父存储中。 对于直接模式下的非根存储对象,此方法不起作用。 对于根存储,它反映了实际设备中的更改;例如,磁盘上的 文件。 对于以直接模式打开的根存储对象,始终在 Release 之前调用 IStorage::Commit 方法。 IStorage::Commit 在直接模式下将所有内存缓冲区刷新到根存储的磁盘,并在失败时返回错误代码。 尽管 Release 还会将内存缓冲区刷新到磁盘,但它在失败时无法返回任何错误代码。 因此,在不首先调用 Commit 的情况下调用 Release 会导致不确定的结果。

语法

HRESULT Commit(
  [in] DWORD grfCommitFlags
);

参数

[in] grfCommitFlags

控制如何将更改提交到存储对象。 有关这些值的定义,请参阅 STGC 枚举。

返回值

此方法可以返回其中一个值。

返回代码 说明
S_OK 对存储对象的更改已成功提交到父级别。 如果指定了STGC_CONSOLIDATE,则存储已成功合并,或者存储过于紧凑,无法进一步合并。
STG_S_MULTIPLEOPENS 提交操作成功,但无法合并存储,因为已使用 STGM_NOSNAPSHOT 标志多次打开存储。
STG_S_CANNOTCONSOLIDATE 提交操作成功,但由于存储模式不正确,无法合并存储。 对于复合文件,存储可能已使用 STGM_NOSCRATCH 标志打开,或者存储可能不是最外层事务处理级别。
STG_S_CONSOLIDATIONFAILED 提交操作成功,但由于内部错误 (内存分配失败) ,无法合并存储。
E_PENDING 仅限异步存储:要提交的部分或全部数据当前不可用。
STG_E_INVALIDFLAG grfCommitFlags 参数的值无效。
STG_E_INVALIDPARAMETER 其中一个参数无效。
STG_E_NOTCURRENT 存储对象的另一个打开实例已提交更改。 因此,当前提交操作可能会覆盖以前的更改。
STG_E_MEDIUMFULL 设备上没有剩余的空间可以提交。
STG_E_TOOMANYOPENFILES 无法完成提交操作,因为打开的文件太多。
STG_E_REVERTED 事务树中存储对象上方的还原操作已失效。

注解

IStorage::Commit 对处于事务处理模式的存储对象进行永久更改,在该模式下,更改累积在缓冲区中,直到调用此方法,才会反映在存储对象中。 另一种方法是在直接模式下打开对象,其中更改会立即反映在存储对象中。 在直接模式下打开的对象不需要调用 IStorage::Commit 来永久更改存储对象。 对以直接模式打开的非根存储调用 IStorage::Commit 方法不起作用。 在直接模式下打开根存储对象可确保将内存缓冲区中的更改写入基础存储设备。

提交操作会将此存储对象及其子项中的当前更改发布到存储层次结构中的上一级别。 若要在提交之前撤消当前更改,请调用 IStorage::Revert 以回滚到上次提交的版本。

调用 IStorage::Commit 不会影响此存储对象的当前打开的嵌套元素。 它们仍然有效,并且可以使用。 但是, IStorage::Commit 方法不会自动提交对这些嵌套元素的更改。 提交操作仅将已知更改发布到存储层次结构中的下一个更高级别。 因此,必须将嵌套级别的事务提交到此存储对象,然后才能将其提交到更高的级别。

在提交操作中,需要采取措施来确保数据在提交过程中受到保护:

  • 将更改提交到根存储对象时,调用方必须检查返回值,以确定操作是否已成功完成,如果尚未成功完成,则 IStorage 的旧已提交内容仍保持不变并可以还原。
  • 如果打开此存储对象时排除了其某些项,则调用方负责在调用提交之前重写它们。 打开存储时需要写入模式才能成功提交。
  • 除非禁止在同一个存储对象上同时使用多个编写器,否则调用此方法的应用程序应在 grfCommitFlags 参数中至少指定STGC_ONLYIFCURRENT,以防止一个编写器所做的更改无意中覆盖另一个编写器所做的更改。
如果存储实现不支持 STGC_CONSOLIDATE 标志,则使用 grfCommitFlags 参数中指定的STGC_CONSOLIDATE调用 IStorage::Commit 将返回值STG_E_INVALIDFLAG。

要求

要求
最低受支持的客户端 Windows 2000 专业版 [桌面应用 |UWP 应用]
最低受支持的服务器 Windows 2000 Server [桌面应用 |UWP 应用]
目标平台 Windows
标头 objidl.h
Library Uuid.lib
DLL Ole32.dll

另请参阅

IStorage - 复合文件实现

IStorage::Revert

STGC