IMAPIFolder::CopyFolder
适用于：Outlook 2013 | Outlook 2016
复制或移动子文件夹。
HRESULT CopyFolder(
ULONG cbEntryID,
LPENTRYID lpEntryID,
LPCIID lpInterface,
LPVOID lpDestFolder,
LPSTR lpszNewFolderName,
ULONG_PTR ulUIParam,
LPMAPIPROGRESS lpProgress,
ULONG ulFlags
);
参数
cbEntryID
[in] lpEntryID 参数指向的条目标识符中的字节计数。
lpEntryID
[in]指向要复制或移动的子文件夹的条目标识符的指针。
lpInterface
[in]指向接口标识符的指针 (IID) ，该接口表示用于访问 lpDestFolder 参数指向的文件夹的接口。 传递 NULL 会导致服务提供程序返回标准文件夹接口 IMAPIFolder ：IMAPIContainer。 lpInterface 的有效值包括IID_IUnknown、IID_IMAPIProp、IID_IMAPIContainer和IID_IMAPIFolder。
lpDestFolder
[in]指向打开文件夹的指针，用于接收复制或移动的子文件夹。
lpszNewFolderName
[in]指向新目标中复制或移动的文件夹的名称的指针。 如果 lpszNewFolderName 设置为 NULL，则源子文件夹的名称将用作目标文件夹的名称。
ulUIParam
[in]进度指示器的父窗口的句柄。 除非设置了 ulFlags 参数中的 FOLDER_DIALOG 标志，否则忽略 ulUIParam 参数。
lpProgress
[in]指向显示进度指示器的进度对象的指针。 如果在 lpProgress 中传递 NULL，则消息存储提供程序使用 MAPI 进度对象实现显示进度指示器。 除非在 ulFlags 中设置了 FOLDER_DIALOG 标志，否则忽略 lpProgress 参数。
ulFlags
[in]控制复制或移动操作的标志的位掩码。 可以设置以下标志：
COPY_SUBFOLDERS
还应复制要复制的子文件夹中的所有子文件夹。 如果未为复制操作设置COPY_SUBFOLDERS，则仅复制 由 lpEntryID 标识的子文件夹。 使用移动操作时，无论是否设置了标志，COPY_SUBFOLDERS行为都是默认值。
FOLDER_DIALOG
请求显示进度指示器。
FOLDER_MOVE
子文件夹将被移动而不是复制。 如果未设置FOLDER_MOVE，则会复制子文件夹。
MAPI_DECLINE_OK
通知消息存储提供程序，如果它通过调用其支持对象的 IMAPISupport：:D oCopyTo 或 IMAPISupport：:D oCopyProps 方法实现 CopyFolder，则 CopyFolder 应立即返回MAPI_E_DECLINE_COPY。
MAPI_UNICODE
目标文件夹的名称采用 Unicode 格式。 如果未设置MAPI_UNICODE标志，则文件夹名称采用 ANSI 格式。
返回值
S_OK
已成功复制或移动指定的文件夹。
MAPI_E_BAD_CHARWIDTH
已设置MAPI_UNICODE标志且消息存储提供程序不支持 Unicode，或者未设置MAPI_UNICODE，并且消息存储提供程序仅支持 Unicode。
MAPI_E_COLLISION
要移动或复制的文件夹的名称与目标文件夹中的子文件夹的名称相同。 邮件存储提供程序需要唯一的文件夹名称。
MAPI_E_DECLINE_COPY
提供程序通过调用支持对象方法实现此方法，并且调用方已传递MAPI_DECLINE_OK标志。
MAPI_E_FOLDER_CYCLE
源文件夹直接或间接包含目标文件夹。 在发现这种情况之前，可能已执行大量工作，因此源和目标文件夹可能会部分修改。
MAPI_W_PARTIAL_COMPLETION
调用成功，但并非所有条目都已成功复制。 返回此警告时，应将调用处理为成功。 若要测试此警告，请使用 HR_FAILED 宏。 有关详细信息，请参阅 使用宏进行错误处理。
备注
IMAPIFolder：：CopyFolder 方法将子文件夹从一个位置复制或移动到另一个位置。 正在复制或移动的子文件夹将作为子文件夹添加到目标文件夹。
针对实现者的说明
如果复制或移动操作涉及多个文件夹（如设置COPY_SUBFOLDERS标志所示），请尽可能完全地为每个文件夹执行操作。 有时，要移动或复制的文件夹之一不存在，或者已移动或复制到其他位置。 除非发生无法控制的故障（例如内存不足、磁盘空间不足或消息存储损坏），否则不要过早停止操作。
尝试在复制的消息中保留所有消息条目标识符。 还应尝试保留条目标识符，但这不是必需的。
给调用方的说明
在以下条件下，应使用这些返回值。
| Condition | 返回值 |
|---|---|
| CopyFolder 已成功复制或移动每封邮件和子文件夹。 | S_OK |
| CopyFolder 无法成功复制或移动每个邮件和子文件夹。 | MAPI_W_PARTIAL_COMPLETION或MAPI_E_NOT_FOUND |
| CopyFolder 无法完成。 | 除 MAPI_E_NOT_FOUND 之外的任何错误值 |
当 CopyFolder 无法完成时，不要假定未完成任何工作。 在遇到错误之前，CopyFolder 可能已经能够复制或移动一个或多个邮件和子文件夹。
如果在 lpEntryID 中传递不存在的文件夹的条目标识符， 则 CopyFolder 将返回MAPI_W_PARTIAL_COMPLETION或MAPI_E_NOT_FOUND，具体取决于邮件存储的实现。
根据消息存储提供程序，原始消息的条目标识符可能会在复制的消息中保留，也可能不保留。 应尽可能保留条目标识符，但不是必需的。 通常可以依赖于以下方案：
在两种不同类型的邮件存储之间移动文件夹时，入口标识符可以保证更改。
在相同类型的两个邮件存储之间移动文件夹时，条目标识符几乎总是会更改。
将文件夹移动到同一邮件存储区中的另一个位置时，条目标识符可能会更改，也可能不会更改，具体取决于邮件存储提供程序。
MFCMAPI 引用
有关 MFCMAPI 示例代码，请参阅下表。
| 文件 | 函数 | Comment |
|---|---|---|
| MsgStoreDlg.cpp |
CMsgStoreDlg：：OnPasteFolder |
MFCMAPI 使用 IMAPIFolder：：CopyFolder 方法将文件夹从一个位置复制到另一个位置。 MFCMAPI 在复制操作期间会记住源文件夹，并在粘贴操作期间实际执行复制。 |