IMAPIFolder::CopyMessages
适用于：Outlook 2013 | Outlook 2016
复制或移动一个或多个邮件。
HRESULT CopyMessages(
LPENTRYLIST lpMsgList,
LPCIID lpInterface,
LPVOID lpDestFolder,
ULONG_PTR ulUIParam,
LPMAPIPROGRESS lpProgress,
ULONG ulFlags
);
参数
lpMsgList
[in]指向 ENTRYLIST 结构的数组的指针，这些结构标识要复制或移动的消息。
lpInterface
[in]指向接口标识符的指针 (IID) ，该接口表示用于访问 lpDestFolder 参数指向的目标文件夹的接口。 传递 NULL 会导致服务提供程序返回标准文件夹接口 IMAPIFolder ：IMAPIContainer。 客户端必须传递 NULL。 其他调用方可以将 lpInterface 参数设置为IID_IUnknown、IID_IMAPIProp、IID_IMAPIContainer或IID_IMAPIFolder。
lpDestFolder
[in]指向打开文件夹的指针，用于接收复制或移动的邮件。
ulUIParam
[in]此方法显示的任何对话框或窗口的父窗口的句柄。 除非客户端在 ulFlags 参数中设置MESSAGE_DIALOG标志并在 lpProgress 参数中传递 NULL，否则将忽略 ulUIParam 参数。
lpProgress
[in]指向显示进度指示器的进度对象的指针。 如果在 lpProgress 中传递 NULL，则消息存储提供程序使用 MAPI 进度对象实现显示进度指示器。 除非在 ulFlags 中设置了 MESSAGE_DIALOG 标志，否则忽略 lpProgress 参数。
ulFlags
[in]控制如何完成复制或移动操作的标志的位掩码。 可以设置以下标志：
MAPI_DECLINE_OK
如果消息存储提供程序通过调用支持对象的 IMAPISupport：:D oCopyTo 或 IMAPISupport：:D oCopyProps 方法实现 IMAPIFolder：：CopyMessages，则通知消息存储提供程序立即返回MAPI_E_DECLINE_COPY。
MESSAGE_DIALOG
在操作继续时显示进度指示器。
MESSAGE_MOVE
将移动或复制消息。 如果未设置MESSAGE_MOVE，则会复制消息。
返回值
S_OK
已成功复制或移动消息。
MAPI_E_DECLINE_COPY
提供程序通过调用支持对象方法实现此方法，并且调用方已传递MAPI_DECLINE_OK标志。
MAPI_W_PARTIAL_COMPLETION
调用成功，但并非所有条目都已成功复制或移动。 返回此警告时，应将调用处理为成功。 若要测试此警告，请使用 HR_FAILED 宏。 有关详细信息，请参阅 使用宏进行错误处理。
备注
IMAPIFolder：：CopyMessages 方法将邮件复制或移动到另一个文件夹。
可以移动或复制以读/写权限打开的消息。
针对实现者的说明
如果在不使用 IMAPISupport：：CopyMessages 方法的情况下将消息复制到另一个消息存储区，则必须首先调用设置了 GENERATE_RECEIPT_ONLY 标志的 IMAPIFolder：：SetReadFlags 。 接收消息存储不负责为复制或移动的消息生成读取报告。 如果要调用 IMAPISupport：：CopyMessages 来实现 IMAPIFolder：：CopyMessages，请不要调用 SetReadFlags;MAPI 将调用它。
实现可以按任意顺序移动或复制消息，并按任意顺序生成读取状态报告。 也就是说，可以在生成任何读取状态报告之前完成消息复制，或者在实现开始复制操作之前发送报告。 但是，无论复制是否成功，都应为所有要复制的消息发送读取报告。
当复制或移动操作涉及多个消息时，请尽可能完全执行该操作。 除非发生无法控制的故障（例如内存不足、磁盘空间不足或消息存储损坏），否则不要过早停止操作。
尝试跨移动或复制操作维护条目标识符。 还应保留条目标识符，但这不是必需的。
移动或复制消息时发送通知，以便预先警告客户端对消息的 IMAPIProp：：SaveChanges 方法的调用可能会失败。
请勿在复制或移动操作中包含消息的状态。 移动或复制消息状态会极大地影响性能。
给调用方的说明
使用 IMAPIFolder：：CopyMessages 填充搜索结果文件夹，其中邮件通常按父文件夹分组。
在以下条件下，应使用这些返回值。
| Condition | 返回值 |
|---|---|
| IMAPIFolder：：CopyMessages 已成功复制或移动每条消息。 | S_OK |
| IMAPIFolder：：CopyMessages 无法成功复制或移动每条消息。 | MAPI_W_PARTIAL_COMPLETION |
| IMAPIFolder：：CopyMessages 无法完成。 | 任何错误值 |
当 IMAPIFolder：：CopyMessages 无法完成时，不要假定未完成任何工作。 IMAPIFolder：：CopyMessages 在遇到错误之前可能已经能够复制或移动一个或多个邮件。