IMAPISupport::DoCopyTo
适用于：Outlook 2013 | Outlook 2016
将一个对象的所有属性（特排除的属性除外）复制或移动到另一个对象。
HRESULT DoCopyTo(
LPCIID lpSrcInterface,
LPVOID lpSrcObj,
ULONG ciidExclude,
LPCIID rgiidExclude,
LPSPropTagArray lpExcludeProps,
ULONG_PTR ulUIParam,
LPMAPIPROGRESS lpProgress,
LPCIID lpDestInterface,
LPVOID lpDestObj,
ULONG ulFlags,
LPSPropProblemArray FAR * lppProblems
);
参数
lpSrcInterface
[in]指向接口标识符的指针 (IID) ，该接口表示用于访问具有要复制或移动的属性的对象。
lpSrcObj
[in]指向对象的指针，该对象具有要复制或移动的属性。
ciidExclude
[in]复制或移动属性时要排除的接口计数。
rgiidExclude
[in]接口标识符数组，指示在将补充信息复制或移动到目标对象时不应使用的接口。
lpExcludeProps
[in]指向属性标记数组的指针，该数组标识应从复制或移动操作中排除的属性标记。 在 lpExcludeProps 参数中传递 NULL 表示应复制或移动对象的所有属性。 当 lpExcludeProps 指向的 SPropTagArray 结构的 cValues 成员设置为 0 时，DoCopyTo 将返回MAPI_E_INVALID_PARAMETER。
ulUIParam
[in]进度指示器的父窗口的句柄。
lpProgress
[in]指向进度指示器实现的指针。 如果在 lpProgress 参数中传递 NULL，MAPI 将提供进度实现。 除非在 ulFlags 参数中设置了 MAPI_DIALOG 标志，否则忽略 lpProgress 参数。
lpDestInterface
[in]指向接口标识符的指针，该接口标识符表示用于访问对象以接收复制或移动的属性的接口。
lpDestObj
[in]指向 对象的指针，用于接收复制或移动的属性。
ulFlags
[in]控制复制或移动操作的标志的位掩码。 可以设置以下标志：
MAPI_DIALOG
显示进度指示器。
MAPI_MOVE
DoCopyTo 应执行移动操作，而不是复制操作。 如果未设置此标志， DoCopyTo 将执行复制操作。
MAPI_NOREPLACE
不应覆盖目标对象中的现有属性。 如果未设置此标志， DoCopyTo 将覆盖现有属性。
lppProblems
[out]输入时，指向 指向 SPropProblemArray 结构的指针的指针;否则为 NULL，指示不需要错误信息。 如果 lppProblems 是输入上的有效指针， DoCopyTo 将返回有关复制一个或多个属性时出现的错误的详细信息。
返回值
S_OK
已成功复制或移动属性。
MAPI_E_COLLISION
要复制或移动的属性已存在于目标对象中，并设置了MAPI_NOREPLACE标志。
MAPI_E_FOLDER_CYCLE
源对象直接或间接包含目标对象。 在发现这种情况之前，可能已执行大量工作，因此源和目标对象可能会部分修改。
MAPI_E_INTERFACE_NOT_SUPPORTED
lpSrcObj 指向的对象不支持 lpSrcInterface 参数标识的接口，或者 lpDestObj 指向的对象不支持 lpDestInterface 参数标识的接口。
MAPI_E_NO_ACCESS
尝试访问调用方权限不足的对象。 如果目标对象与源对象相同，则返回此错误。
MAPI_E_INVALID_PARAMETER
lpSrcInterface 参数为 NULL。
以下值可以在 SPropProblemArray 结构中返回，但不能作为 DoCopyTo 的返回值。 这些错误适用于单个属性。
MAPI_E_BAD_CHARWIDTH
已设置MAPI_UNICODE标志， DoCopyTo 不支持 Unicode，或者未设置MAPI_UNICODE并且 DoCopyTo 仅支持 Unicode。
MAPI_E_COMPUTED
属性不能由调用方修改，因为它是一个只读属性，由目标对象的所有者计算。 此错误并不严重;调用方应允许复制操作继续。
MAPI_E_INVALID_TYPE
属性类型无效。
MAPI_E_UNEXPECTED_TYPE
属性类型不是调用方所需的类型。
备注
IMAPISupport：:D oCopyTo 方法为消息存储提供程序支持对象实现。 消息存储提供程序可以调用 DoCopyTo 来为其文件夹和邮件实现 IMAPIProp：：CopyTo 方法。
默认情况下， DoCopyTo 将一个对象的所有属性复制或移动到另一个对象。 源对象中的任何子对象都会自动包含在操作中，并全部复制或移动。
如果目标对象中已存在任何复制或移动的属性，则新属性将覆盖现有属性，除非在 ulFlags 参数中设置了 MAPI_NOREPLACE 标志。 目标对象中未覆盖的现有信息保持不变。
给调用方的说明
若要从复制或移动操作中排除属性，请在 lpExcludeProps 参数中包含其属性标记。 如果传递使用 PROP_TAG 宏从属性标记数组中的特定标识符生成属性标记的结果，则将排除具有该标识符的所有属性。 例如，属性标记数组中的以下条目会导致排除标识符为 0x8002 的所有属性，而不考虑类型：
PROP_TAG(PT_LONG, 0x8002)
若要避免在将邮件复制到其他文件夹时复制邮件的传递时间，请在属性标记 exclude 数组中指定 PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime) 。 若要排除邮件的收件人列表，请将 PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) 属性添加到 exclude 数组。 若要排除邮件的附件，请将 PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) 属性添加到数组。
同样，若要防止复制或移动文件夹或通讯簿容器的层次结构或内容表，请在属性标记排除数组中包含 PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) 或 PR_CONTAINER_CONTENTS (PidTagContainerContents) 。
忽略 lppProblems 参数的 SPropProblemArray 结构中返回的MAPI_E_COMPUTED错误。
lpSrcInterface 指向的接口标识符通常与 lpDestInterface 指向的接口标识符相同。
如果在 lpDestInterface 中传递可接受的接口标识符，但在 lpDestObj 中传递的指针无效，则结果不可预测。 这很可能会导致提供程序失败。
相反，如果知道不应复制或移动的补充信息，请在 rgiidExclude 参数中传递的数组中添加要排除的接口的接口标识符。 例如，如果要复制邮件，但不复制其任何邮件附件，请在 rgiidExclude 数组中传递IID_IMessage。 DoCopyTo 忽略 rgiidExclude 中列出的任何它无法识别的接口。
使用 rgiidExclude 参数排除接口时，它还排除从该接口派生的所有接口。 例如，排除 IMAPIContainer 接口会导致排除文件夹或通讯簿容器，具体取决于提供程序的类型。 不要排除 IMAPIProp 或 IUnknown ，因为有这么多接口派生自它们。
DoCopyTo 报告应用于整个操作的全局错误，以及应用于单个属性的单个错误。 这些单独的错误置于 SPropProblemArray 结构中。 可以通过为属性问题数组结构参数传递 NULL（而不是有效的指针）来抑制属性级别的错误报告。
如果要接收有关错误的信息，请在 lppProblems 参数中传递有效的 SPropProblemArray 结构指针。 当 DoCopyTo 返回S_OK时，检查结构中各个属性可能存在的错误。 当 DoCopyTo 返回错误时，SPropProblemArray 结构中不会返回任何信息。 请改为调用 IMAPISupport：：GetLastError 方法来检索详细的错误信息。
如果 DoCopyTo 返回S_OK，则通过调用 MAPIFreeBuffer 函数释放返回的 SPropProblemArray 结构。
如果在 DoCopyTo 调用上发生全局错误，请不要使用或释放 SPropProblemArray 结构。 提供程序应忽略 DoCopyTo 返回的 SPropProblemArray 结构中的 ulIndex 成员。