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
[в] Число байтов в идентификаторе записи, на который указывает параметр lpEntryID .
lpEntryID
[в] Указатель на идентификатор записи вложенной папки для копирования или перемещения.
lpInterface
[в] Указатель на идентификатор интерфейса (IID), представляющий интерфейс, используемый для доступа к папке, на которую указывает параметр lpDestFolder . Передача NULL приводит к тому, что поставщик услуг возвращает стандартный интерфейс папок IMAPIFolder : IMAPIContainer. Допустимые значения для lpInterface : IID_IUnknown, IID_IMAPIProp, IID_IMAPIContainer и IID_IMAPIFolder.
lpDestFolder
[в] Указатель на открытую папку для получения скопированной или перемещенной вложенной папки.
lpszNewFolderName
[в] Указатель на имя скопированной или перемещенной папки в новом назначении. Если для параметра lpszNewFolderName задано значение NULL, имя исходной вложенной папки используется для имени целевой папки.
ulUIParam
[в] Дескриптор родительского окна индикатора хода выполнения. Параметр ulUIParam игнорируется, если не задан флаг FOLDER_DIALOG в параметре ulFlags .
lpProgress
[в] Указатель на объект выполнения, отображающий индикатор хода выполнения. Если в lpProgress передается значение NULL, поставщик хранилища сообщений отображает индикатор хода выполнения с помощью реализации объекта хода выполнения MAPI. Параметр lpProgress игнорируется, если флаг FOLDER_DIALOG не установлен в ulFlags.
ulFlags
[в] Битовая маска флагов, управляющая операцией копирования или перемещения. Можно задать следующие флаги:
COPY_SUBFOLDERS
Все вложенные папки в копируемых вложенных папках также должны быть скопированы. Если COPY_SUBFOLDERS не задано для операции копирования, копируется только вложенная папка, определяемая lpEntryID . При операции перемещения поведение COPY_SUBFOLDERS по умолчанию независимо от того, установлен ли флаг.
FOLDER_DIALOG
Запрашивает отображение индикатора хода выполнения.
FOLDER_MOVE
Вложенная папка должна быть перемещена, а не скопирована. Если FOLDER_MOVE не задано, вложенная папка копируется.
MAPI_DECLINE_OK
Сообщает поставщику хранилища сообщений о том, что если он реализует CopyFolder путем вызова метода IMAPISupport::D oCopyTo или IMAPISupport::D oCopyProps , CopyFolder должен немедленно вернуть MAPI_E_DECLINE_COPY.
MAPI_UNICODE
Имя целевой папки имеет формат Юникода. Если флаг MAPI_UNICODE не задан, имя папки будет в формате ANSI.
Возвращаемое значение
S_OK
Указанная папка успешно скопирована или перемещена.
MAPI_E_BAD_CHARWIDTH
Либо был установлен флаг MAPI_UNICODE, а поставщик хранилища сообщений не поддерживает Юникод, либо MAPI_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 запоминает исходную папку во время операции копирования и фактически выполняет копирование во время операции вставки. |