IMAPIProp::CopyProps

项目
04/04/2023

适用于：Outlook 2013 | Outlook 2016

复制或移动所选属性。

HRESULT CopyProps(
  LPSPropTagArray lpIncludeProps,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  LPCIID lpInterface,
  LPVOID lpDestObj,
  ULONG ulFlags,
  LPSPropProblemArray FAR * lppProblems
);

参数

lpIncludeProps

[in]指向属性标记数组的指针，该数组指定要复制或移动的属性。 PR_NULL (PidTagNull) 不能包含在数组中。 lpIncludeProps 参数不能为 null。

ulUIParam

[in]进度指示器的父窗口的句柄。

lpProgress

[in]指向进度指示器实现的指针。如果在 lpProgress 参数中传递 null，则使用 MAPI 实现显示进度指示器。除非在 ulFlags 参数中设置了 MAPI_DIALOG 标志，否则忽略 lpProgress 参数。

lpInterface

[in]指向接口标识符的指针 (IID) ，该接口表示必须用于访问 lpDestObj 参数指向的对象。 lpInterface 参数不得为 null。

lpDestObj

[in]指向对象的指针，用于接收复制或移动的属性。

ulFlags

[in]控制复制或移动操作的标志的位掩码。可以设置以下标志：

MAPI_DECLINE_OK

如果 CopyProps 调用 IMAPISupport：:D oCopyProps 方法来处理复制或移动操作，则它应立即返回并MAPI_E_DECLINE_COPY错误值。 MAPI 设置MAPI_DECLINE_OK标志以限制递归。客户端不设置此标志。

MAPI_DIALOG

显示进度指示器。

MAPI_MOVE

CopyProps 应执行移动操作，而不是复制操作。如果未设置此标志， CopyProps 将执行复制操作。

MAPI_NOREPLACE

不应覆盖目标对象中的现有属性。如果未设置此标志， CopyProps 将覆盖现有属性。

lppProblems

[in，out]输入时，指向指向 SPropProblemArray 结构的指针的指针;否则为 null，指示不需要错误信息。如果 lppProblems 是输入上的有效指针， CopyProps 将返回有关复制一个或多个属性时出现的错误的详细信息。

返回值

S_OK

已成功复制或移动属性。

MAPI_E_COLLISION

无法复制子对象，因为目标对象中已存在具有相同显示名称的子对象（由 PR_DISPLAY_NAME (PidTagDisplayName) 属性定义）。

MAPI_E_DECLINE_COPY

服务提供程序不实现复制操作。

MAPI_E_FOLDER_CYCLE

直接或间接执行复制或移动操作的源对象包含目标对象。在发现这种情况之前，可能已执行大量工作，因此源和目标对象可能会部分修改。

MAPI_E_INTERFACE_NOT_SUPPORTED

目标对象不支持 lpInterface 参数标识的接口。

MAPI_E_NO_ACCESS

尝试访问调用方权限不足的对象。如果目标对象与源对象相同，则返回此错误。

以下值可以在 SPropProblemArray 结构中返回，但不能作为 CopyProps 的返回值。这些错误适用于单个属性。

MAPI_E_BAD_CHARWIDTH

已设置MAPI_UNICODE标志且 CopyProps 不支持 Unicode，或者未设置MAPI_UNICODE且 CopyProps 仅支持 Unicode。

MAPI_E_COMPUTED

属性不能由调用方修改，因为它是一个只读属性，由目标对象的所有者计算。此错误并不严重;调用方应允许复制操作继续。

MAPI_E_INVALID_TYPE

属性类型无效。

MAPI_E_UNEXPECTED_TYPE

属性类型不是调用方所需的类型。

备注

IMAPIProp：：CopyProps 方法将所选属性从当前对象复制或移动到目标对象。 CopyProps 主要用于答复和转发邮件，其中只有原始邮件中的某些属性随答复或转发副本一起传输。

无论使用 SPropTagArray 结构指示的属性，源对象中的任何子对象都会自动包含在操作中，并全部复制或移动这些子对象。默认情况下， CopyProps 将覆盖目标对象中与源对象中的属性匹配的任何属性。如果目标对象中已存在任何复制或移动的属性，则新属性将覆盖现有属性，除非在 ulFlags 参数中设置了 MAPI_NOREPLACE 标志。目标对象中未覆盖的现有信息保持不变。

针对实现者的说明

可以提供 CopyProps 的完整实现，也可以依赖于 MAPI 在其支持对象中提供的实现。如果要使用 MAPI 实现，请调用 IMAPISupport：:D oCopyProps 方法。但是，如果将处理委托给 DoCopyProps ，并且传递了MAPI_DECLINE_OK标志，请避免支持调用并返回MAPI_E_DECLINE_COPY。 MAPI 将使用此标志调用你，以避免在复制文件夹时可能发生的递归。

由于复制操作可能很长，因此应显示进度指示器。使用在 lpProgress 参数中传递的 IMAPIProgress 实现（如果有）。如果 lpProgress 为 null，请调用 IMAPISupport：:D oProgressDialog 方法以使用 MAPI 实现。

给调用方的说明

不要设置MAPI_DECLINE_OK标志;它由 MAPI 在其对消息存储提供程序 CopyProps 实现的调用中使用。

由于复制和移动操作可能需要一些时间，因此最好通过设置MAPI_DIALOG标志来请求显示进度指示器。可以将 lpProgress 参数设置为 IMAPIProgress 的实现（如果有）或设置为 null。如果 lpProgress 为 null，CopyProps 将使用 MAPI 提供的默认进度指示器。

可以通过不设置MAPI_DIALOG标志来禁止显示进度指示器。 CopyProps 将忽略 ulUIParam 和 lpProgress 参数，并避免显示指示器。

CopyProps 可以报告全局错误和单个错误，或者与一个或多个属性一起发生的错误。这些单独的错误置于 SPropProblemArray 结构中。可以通过为属性问题数组结构参数传递 null 而不是有效的指针，在属性级别禁止报告错误。

如果要接收有关错误的信息，请在 lppProblems 参数中传递有效的 SPropProblemArray 结构指针。 当 CopyProps 返回S_OK时，检查结构中各个属性可能存在的错误。 当 CopyProps 返回错误时，SPropProblemArray 结构中不会返回任何信息。请改为调用 IMAPIProp：：GetLastError 方法来检索详细的错误信息。

如果 CopyProps 返回S_OK，则通过调用 MAPIFreeBuffer 函数释放返回的 SPropProblemArray 结构。

如果要复制源对象类型唯一的属性，必须确保目标对象的类型相同。 CopyProps 不会阻止将通常属于一种类型的对象的属性与另一种类型的对象相关联。由你来复制对目标对象有意义的属性。例如，不应将消息属性复制到通讯簿容器。

为了确保在同一类型的对象之间复制，检查源对象和目标对象是同一类型，方法是比较对象指针或调用 IUnknown：：QueryInterface 方法。将 lpInterface 指向的接口标识符设置为源对象的标准接口。此外，请确保对象类型或 PR_OBJECT_TYPE (PidTagObjectType) 属性对于这两个对象相同。例如，如果要从消息复制，请将 lpInterface 设置为 IID_IMessage，并将这两个对象的 PR_OBJECT_TYPE 设置为MAPI_MESSAGE。

如果在 lpDestObj 参数中传递了无效指针，则结果不可预知。

若要复制邮件的收件人列表，请调用邮件的 CopyProps 方法，并在属性标记数组中包含 PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) 属性。若要复制邮件的附件，请包含 PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) 属性。

若要复制文件夹或通讯簿容器的层次结构或内容表，请在属性标记数组中包含 PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) 或 PR_CONTAINER_CONTENTS (PidTagContainerContents) 属性。若要包含文件夹的关联内容表，请在数组中包含 PR_FOLDER_ASSOCIATED_CONTENTS (PidTagFolderAssociatedContents) 属性。

MFCMAPI 引用

有关 MFCMAPI 示例代码，请参阅下表。

文件	函数	Comment
MAPIFunctions.cpp	CopyNamedProps	MFCMAPI 使用 IMAPIProp：：CopyProps 方法将命名属性从一条消息复制到另一条消息。
SingleMAPIPropListCtrl.cpp	CSingleMAPIPropListCtrl：：OnPasteProperty	MFCMAPI 使用 IMAPIProp：：CopyProps 方法粘贴已从另一个对象复制的属性。