IMAPIFolder::CopyMessages
Область применения: Outlook 2013 | Outlook 2016
Копирует или перемещает одно или несколько сообщений.
HRESULT CopyMessages(
LPENTRYLIST lpMsgList,
LPCIID lpInterface,
LPVOID lpDestFolder,
ULONG_PTR ulUIParam,
LPMAPIPROGRESS lpProgress,
ULONG ulFlags
);
Параметры
lpMsgList
[в] Указатель на массив структур ENTRYLIST , которые определяют сообщение или сообщения для копирования или перемещения.
lpInterface
[в] Указатель на идентификатор интерфейса (IID), представляющий интерфейс, используемый для доступа к целевой папке, на которую указывает параметр lpDestFolder . Передача результатов NULL в поставщике услуг, возвращающего стандартный интерфейс папок, IMAPIFolder : IMAPIContainer. Клиенты должны передавать значение NULL. Другие вызывающие могут задать для параметра lpInterface значение IID_IUnknown, IID_IMAPIProp, IID_IMAPIContainer или IID_IMAPIFolder.
lpDestFolder
[в] Указатель на открытую папку для получения скопированных или перемещенных сообщений.
ulUIParam
[в] Дескриптор родительского окна любых диалоговых окон или окон, отображаемых этим методом. Параметр ulUIParam игнорируется, если клиент не задает флаг MESSAGE_DIALOG в параметре ulFlags и не передает null в параметре lpProgress .
lpProgress
[в] Указатель на объект выполнения, отображающий индикатор хода выполнения. Если в lpProgress передается значение NULL, поставщик хранилища сообщений отображает индикатор хода выполнения с помощью реализации объекта хода выполнения MAPI. Параметр lpProgress игнорируется, если флаг MESSAGE_DIALOG не установлен в ulFlags.
ulFlags
[в] Битовая маска флагов, управляющая выполнением операции копирования или перемещения. Можно задать следующие флаги:
MAPI_DECLINE_OK
Сообщает поставщику хранилища сообщений немедленно вернуть MAPI_E_DECLINE_COPY, если он реализует IMAPIFolder::CopyMessages путем вызова метода IMAPISupport::D oCopyTo или IMAPISupport::D oCopyProps объекта поддержки .
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 необходимо сначала вызвать IMAPIFolder::SetReadFlags с установленным флагом GENERATE_RECEIPT_ONLY. Принимающее хранилище сообщений не отвечает за создание отчетов о чтении для скопированных или перемещенных сообщений. Если вы вызываете 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 , возможно, удалось скопировать или переместить одно или несколько сообщений до возникновения ошибки.