IMAPIProp::SaveChanges

适用于:Outlook 2013 | Outlook 2016

对自上次保存操作以来对对象所做的任何更改进行永久更改。

HRESULT SaveChanges(
  ULONG ulFlags
);

参数

ulFlags

[in]标志的位掩码,用于控制调用 IMAPIProp::SaveChanges 方法时对象发生的情况。 可以设置以下标志:

NON_EMS_XP_SAVE

指示消息尚未从Microsoft Exchange Server传递。 此标志应与 IMAPIFolder::CreateMessage 方法和 ITEMPROC_FORCE 标志结合使用,以在个人文件夹文件 (PST) 存储通知任何侦听客户端邮件已到达之前,向 PST 存储指示邮件符合规则处理条件。 此规则处理仅适用于在不是Exchange Server的服务器上使用 IMAPIFolder::CreateMessage 创建的新消息,在这种情况下,Exchange Server已处理邮件的规则。

FORCE_SAVE

应将更改写入 对象,重写以前对 对象所做的任何更改,并且应关闭对象。 必须设置读/写权限才能使操作成功。 FORCE_SAVE标志在上一次对 SaveChanges 的调用返回MAPI_E_OBJECT_CHANGED后使用。

KEEP_OPEN_READONLY

应提交更改,并且对象应保持打开状态以供读取。 不会进行其他更改。

KEEP_OPEN_READWRITE

应提交更改,并且对象应保持打开状态以获取读/写权限。 此标志通常在首次打开对象以获取读/写权限时设置。 允许对 对象的后续更改。

MAPI_DEFERRED_ERRORS

允许 SaveChanges 成功返回,可能是在更改完全提交之前。

SPAMFILTER_ONSAVE

对正在保存的邮件启用垃圾邮件筛选。 垃圾邮件筛选支持只有在发件人的电子邮件地址类型为简单邮件传输协议 (SMTP) 且正在将邮件保存到个人文件夹文件 (PST) 存储区的情况下可用。

返回值

S_OK

更改承诺成功。

MAPI_E_NO_ACCESS

如果设置了KEEP_OPEN_READONLY,SaveChanges 无法使对象保持打开状态以获取只读权限;如果设置了KEEP_OPEN_READWRITE,则无法保持读取/写入权限。 不会提交任何更改。

MAPI_E_OBJECT_CHANGED

对象在打开后已更改。

MAPI_E_OBJECT_DELETED

对象自打开后已被删除。

备注

IMAPIProp::SaveChanges 方法使支持处理事务模型的对象(如消息、附件、通讯簿容器和消息用户对象)的属性更改永久。 不支持事务的对象(如文件夹、邮件存储和配置文件部分)会立即永久更改。 不需要调用 SaveChanges

由于在保存所有属性之前,服务提供程序不必为其对象生成入口标识符,因此对象的 PR_ENTRYID (PidTagEntryId) 属性在调用其 SaveChanges 方法后可能不可用。 某些提供程序等到 在 SaveChanges 调用上设置KEEP_OPEN_READONLY标志。 KEEP_OPEN_READONLY指示在当前调用中保存的更改将是将对 对象进行的最后一次更改。

在客户端使用 SaveChanges 保存邮件更改并使用 IUnknown::Release 方法释放邮件对象之前,某些邮件存储实现不会在文件夹中显示新创建的邮件。 此外,在调用 SaveChanges 之前,某些对象实现无法为新创建的对象生成PR_ENTRYID属性,而有些对象实现只能在使用 ulFlags 中设置KEEP_OPEN_READONLY调用 SaveChanges 之后才能执行此操作。

针对实现者的说明

如果收到KEEP_OPEN_READONLY标志,则可以选择将对象的访问权限保留为可读/写。 但是,在传递KEEP_OPEN_READWRITE标志时,提供程序永远不能将对象保留为只读状态。

当客户端将多个附件保存到多个邮件时,它会为每个附件和每条消息调用 SaveChanges 方法。 客户端通常会为上述每个调用设置MAPI_DEFERRED_ERRORS,但最后一个调用除外。 可以通过最后一次调用或更早的调用返回错误。 甚至可以忽略 标志。

如果KEEP_OPEN_READWRITE或KEEP_OPEN_READONLY与MAPI_DEFERRED_ERRORS一起设置,则可以忽略错误的延迟请求。 如果未在 ulFlags 中设置MAPI_DEFERRED_ERRORS,则可以为 SaveChanges 调用返回以前延迟的错误之一。

远程传输提供程序是否提供此方法的功能实现是可选的,取决于实现中的其他设计选项。 如果实现此方法,请根据此处的文档执行此操作。 由于未处理文件夹对象和状态对象,因此远程传输提供程序的 SaveChanges 实现至少必须返回S_OK而不实际执行任何工作。

给调用方的说明

如果客户端传递KEEP_OPEN_READONLY,调用 IMAPIProp::SetProps 方法,然后再次调用 SaveChanges ,则同一实现可能会失败。

从设置了KEEP_OPEN_READWRITE的调用接收MAPI_E_NO_ACCESS后,你将继续对 对象拥有读/写权限。 可以再次调用 SaveChanges ,传递KEEP_OPEN_READONLY标志或不使用带有KEEP_OPEN_SUFFIX的标志。

提供程序是否支持 KEEP_OPEN_READWRITE 标志取决于提供程序的实现。

若要指示 SaveChanges 之后对对象进行的唯一调用是 IUnknown::Release,请不为 ulFlags 参数设置任何标志。 SaveChanges 中的错误指示它无法使挂起的更改永久化。 不同的提供程序以不同的方式处理 SaveChanges 调用上缺少标志的情况。 某些提供程序将此状态视为KEEP_OPEN_READONLY;其他提供程序将其解释为与 KEEP_OPEN_READWRITE 相同。 其他提供程序在 SaveChanges 调用上未收到标志时,还会关闭对象。

某些属性(通常是计算属性)在调用 SaveChanges (在某些情况下为 Release)之前无法处理。

进行批量更改(如将附件保存到多个邮件)时,通过在 ulFlags 中设置MAPI_DEFERRED_ERRORS标志来延迟错误处理。 如果将多个附件保存到多个邮件,请对每个附件进行一次 SaveChanges 调用,对每个邮件进行一次 SaveChanges 调用。 为每个附件调用和所有邮件设置MAPI_DEFERRED_ERRORS标志,最后一个邮件除外。

如果 SaveChanges 返回MAPI_E_OBJECT_CHANGED,检查原始对象是否已修改。 如果是,请警告用户,用户可以请求更改覆盖以前的更改,或将对象保存到其他位置。 如果原始对象已被删除,警告用户,让他们有机会将对象保存在其他位置。

不能对已删除的打开对象使用FORCE_SAVE标志调用 SaveChanges

如果 SaveChanges 返回错误,则要保存其更改的对象将保持打开状态,而不考虑 ulFlags 参数中设置的标志。

重要

ulFlags NON_EMS_XP_SAVE 和 SPAMFILTER_ONSAVE 可能未在当前具有的可下载头文件中定义,在这种情况下,可以使用以下值将其添加到代码中:#define SPAMFILTER_ONSAVE ((ULONG) 0x00000080)>#define NON_EMS_XP_SAVE ((ULONG) 0x00001000)

有关详细信息,请参阅 保存 MAPI 属性

另请参阅

IMAPIProp::SetProps
PidTagEntryId 规范属性
IMAPIProp:I 未知的保存 MAPI 属性