IMAPIProp::CopyTo
适用于：Outlook 2013 | Outlook 2016
复制或移动除明确排除的属性以外的所有属性。
HRESULT CopyTo(
ULONG ciidExclude,
LPCIID rgiidExclude,
LPSPropTagArray lpExcludeProps,
ULONG_PTR ulUIParam,
LPMAPIPROGRESS lpProgress,
LPCIID lpInterface,
LPVOID lpDestObj,
ULONG ulFlags,
LPSPropProblemArray FAR * lppProblems
);
参数
ciidExclude
[in]复制或移动属性时要排除的接口计数。
rgiidExclude
[in]接口标识符的数组 (IID) 指定在复制补充信息或移动到目标对象时不应使用的接口。
lpExcludeProps
[in]指向属性标记数组的指针，该数组标识应从复制或移动操作中排除的属性标记。 在 lpExcludeProps 参数中传递 null 表示应复制或移动对象的所有属性。 当 lpExcludeProps 指向的 SPropProblemArray 结构的 cValues 成员设置为 0 时，CopyTo 返回MAPI_E_INVALID_PARAMETER。
ulUIParam
[in]进度指示器的父窗口的句柄。
lpProgress
[in]指向进度指示器实现的指针。 如果在 lpProgress 参数中传递 null，MAPI 将提供进度实现。 除非在 ulFlags 参数中设置了 MAPI_DIALOG 标志，否则忽略 lpProgress 参数。
lpInterface
[in]指向接口标识符的指针 (IID) ，该接口表示用于访问 lpDestObj 参数指向的对象。 lpInterface 参数不得为 null。
lpDestObj
[in]指向 对象的指针，用于接收复制或移动的属性。
ulFlags
[in]控制复制或移动操作的标志的位掩码。 可以设置以下标志：
MAPI_DECLINE_OK
如果 CopyTo 调用 IMAPISupport：:D oCopyTo 方法来处理复制或移动操作，则它应立即返回，MAPI_E_DECLINE_COPY错误值。 MAPI 设置MAPI_DECLINE_OK标志以限制递归。 客户端不设置此标志。
MAPI_DIALOG
显示进度指示器。
MAPI_MOVE
CopyTo 应执行移动操作而不是复制操作。 如果未设置此标志， CopyTo 将执行复制操作。
MAPI_NOREPLACE
不应覆盖目标对象中的现有属性。 如果未设置此标志， CopyTo 将覆盖现有属性。
lppProblems
[in，out]输入时，指向 指向 SPropProblemArray 结构的指针的指针;否则为 null，指示不需要错误信息。 如果 lppProblems 是输入上的有效指针， 则 CopyTo 将返回有关复制一个或多个属性时出现的错误的详细信息。
返回值
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 结构中返回，但不能作为 CopyTo 的返回值。 以下错误适用于单个属性：
MAPI_E_BAD_CHARWIDTH
已设置MAPI_UNICODE标志且 CopyTo 不支持 Unicode，或者未设置MAPI_UNICODE且 CopyTo 仅支持 Unicode。
MAPI_E_COMPUTED
属性不能由调用方修改，因为它是一个只读属性，由目标对象的所有者计算。 此错误并不严重;调用方应允许复制操作继续。
MAPI_E_INVALID_TYPE
属性类型无效。
MAPI_E_UNEXPECTED_TYPE
属性类型不是调用方所需的类型。
备注
默认情况下， IMAPIProp：：CopyTo 方法将当前对象的所有属性复制或移动到目标对象。 当应精确复制或移动对象时，使用 CopyTo，其所有或大部分属性保持不变。
源对象中的任何子对象都会自动包含在操作中，并全部复制或移动。 默认情况下， CopyTo 覆盖目标对象中与源对象中的属性匹配的任何属性。 如果目标对象中已存在任何复制或移动的属性，则新属性将覆盖现有属性，除非在 ulFlags 参数中设置了 MAPI_NOREPLACE 标志。 目标对象中未覆盖的现有信息保持不变。
针对实现者的说明
可以提供 CopyTo 的完整实现，也可以依赖于 MAPI 在其支持对象中提供的实现。 如果要使用 MAPI 实现，请调用 IMAPISupport：:D oCopyTo。 但是，如果将处理委托给 DoCopyTo 并且传递了MAPI_DECLINE_OK标志，请避免支持调用并返回MAPI_E_DECLINE_COPY。 MAPI 将使用此标志调用，以避免复制文件夹时可能发生的递归。
由于复制操作可能很长，因此应显示进度指示器。 使用 lpProgress 参数中传递的 IMAPIProgress 实现（如果有）。 如果 lpProgress 为 null，请调用 IMAPISupport：:D oProgressDialog 方法以使用 MAPI 实现。
不要尝试在目标对象中设置任何已知的只读属性;请改为返回MAPI_E_NO_ACCESS。
源对象和目标对象应使用相同的接口。 如果未设置 lpInterface ，则返回MAPI_E_INVALID_PARAMETER。
如果排除所有已知接口，则返回MAPI_E_INTERFACE_NOT_SUPPORTED。
给调用方的说明
不要设置MAPI_DECLINE_OK标志;MAPI 在调用消息存储提供程序 CopyTo 实现时使用它。
由于复制和移动操作可能需要一些时间，因此应通过设置MAPI_DIALOG标志来请求显示进度指示器。 可以将 lpProgress 参数设置为 IMAPIProgress 的实现（如果有）或设置为 null。 如果 lpProgress 为 null，CopyTo 将使用 MAPI 提供的默认进度指示器。
可以通过不设置MAPI_DIALOG标志来禁止显示进度指示器。 CopyTo 将忽略 ulUIParam 和 lpProgress 参数，并且不会显示指示器。
CopyTo 可以报告全局错误和单个错误，或者与一个或多个属性一起发生的错误。 这些单独的错误置于 SPropProblemArray 结构中。 可以通过为属性问题数组结构参数传递 null 而不是有效的指针，在属性级别禁止报告错误。
如果要接收有关错误的信息，请在 lppProblems 参数中传递有效的 SPropProblemArray 结构指针。 当 CopyTo 返回S_OK时，检查结构中各个属性可能存在的错误。 当 CopyTo 返回错误时，SPropProblemArray 结构中不会返回任何信息。 请改为调用 IMAPIProp：：GetLastError 来检索详细的错误信息。
如果 CopyTo 返回S_OK，则通过调用 MAPIFreeBuffer 函数释放返回的 SPropProblemArray 结构。
如果复制源对象类型唯一的属性，必须确保目标对象属于同一类型。 CopyTo 不会阻止将通常属于一种类型的对象的属性与另一种类型的对象相关联。 由你来复制对目标对象有意义的属性。 例如，不应将消息属性复制到通讯簿容器。
为了确保在同一类型的对象之间复制，检查源对象和目标对象是同一类型，方法是比较对象指针或调用 IUnknown：：QueryInterface。 将 lpInterface 指向的接口标识符设置为源对象的标准接口。 此外，请确保对象类型或 PR_OBJECT_TYPE (PidTagObjectType) 属性对于这两个对象相同。 例如，如果从邮件复制，请将 lpInterface 设置为 IID_IMessage，并将这两个对象的 PR_OBJECT_TYPE 设置为MAPI_MESSAGE。
如果在 lpDestObj 参数中传递了无效指针，则结果不可预知。
排除 CopyTo 调用的属性可能很有用。 例如，某些对象具有特定于对象的单个实例的属性，例如消息传递的日期和时间。 若要避免在将邮件复制到其他文件夹时复制邮件的传递时间，请在属性标记 exclude 数组中指定 PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime) 。 若要排除邮件的收件人列表，请将 PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) 属性添加到 exclude 数组。 若要排除邮件的附件，请将 PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) 属性添加到数组。
同样，通过在属性标记排除数组中包含 PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) 或 PR_CONTAINER_CONTENTS (PidTagContainerContents) ，防止复制或移动文件夹或通讯簿容器的层次结构或内容表。
若要从复制或移动操作中排除属性，请在 lpExcludeProps 参数中包含其属性标记。 如果传递 PROP_TAG 宏的结果以从属性标记数组中的特定标识符生成属性标记，则将排除具有该标识符的所有属性。 例如，属性标记数组中的以下条目会导致排除标识符为 0x8002 的所有属性，而不考虑类型：
PROP_TAG(PT_LONG, 0x8002)
PR_NULL (PidTagNull) 属性标记不能包含在 lpExcludeProps 数组中。
CopyTo 功能用于排除接口的有用性可能不如排除属性的有用性那么明显。 复制到不了解一组属性的对象时，可以排除接口。 例如，如果将属性从文件夹复制到附件，则附件可以使用的唯一属性是可用于任何 IMAPIProp 实现的泛型属性。 通过从复制操作中排除 IMAPIFolder ，附件将不接收任何更具体的文件夹属性。
使用 rgiidExclude 参数排除接口时，它还排除从该接口派生的所有接口。 例如，排除 IMAPIContainer 会导致排除文件夹或通讯簿容器，具体取决于提供程序的类型。 不要排除 IMAPIProp 或 IUnknown ，因为有这么多接口派生自它们。
忽略 lppProblems 参数的 SPropProblemArray 结构中返回的MAPI_E_COMPUTED错误。
MFCMAPI 引用
有关 MFCMAPI 示例代码，请参阅下表。
| 文件 | 函数 | Comment |
|---|---|---|
| File.cpp |
LoadFromMSG |
MFCMAPI 使用 IMAPIProp：：CopyTo 方法将属性从.msg文件复制到 IMAPIMessageSite 对象。 |
| FolderDlg.cpp |
CFolderDlg：：HandlePaste |
在粘贴操作期间，MFCMAPI 使用 IMAPIProp：：CopyTo 方法将属性从源消息复制到目标消息。 |
另请参阅
IMAPISupport::DoProgressDialog