IMAPIProp::CopyProps

Статья
04/04/2023

Область применения: Outlook 2013 | Outlook 2016

Копирует или перемещает выбранные свойства.

HRESULT CopyProps(
  LPSPropTagArray lpIncludeProps,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  LPCIID lpInterface,
  LPVOID lpDestObj,
  ULONG ulFlags,
  LPSPropProblemArray FAR * lppProblems
);

Параметры

lpIncludeProps

[в] Указатель на массив тегов свойств, указывающий свойства для копирования или перемещения. PR_NULL (PidTagNull) нельзя включить в массив. Параметр lpIncludeProps не может иметь значение NULL.

ulUIParam

[в] Дескриптор родительского окна индикатора хода выполнения.

lpProgress

[в] Указатель на реализацию индикатора хода выполнения. Если в параметре lpProgress передается значение NULL, индикатор хода выполнения отображается с помощью реализации MAPI. Параметр lpProgress игнорируется, если в параметре ulFlags не установлен флаг MAPI_DIALOG.

lpInterface

[в] Указатель на идентификатор интерфейса (IID), представляющий интерфейс, который должен использоваться для доступа к объекту, на который указывает параметр lpDestObj . Параметр lpInterface не должен иметь значение NULL.

lpDestObj

[в] Указатель на объект для получения скопированных или перемещенных свойств.

ulFlags

[в] Битовая маска флагов, управляющая операцией копирования или перемещения. Можно задать следующие флаги:

MAPI_DECLINE_OK

Если CopyProps вызывает метод IMAPISupport::D oCopyProps для обработки операции копирования или перемещения, он должен немедленно вернуться со значением ошибки MAPI_E_DECLINE_COPY. Флаг MAPI_DECLINE_OK задается MAPI для ограничения рекурсии. Клиенты не устанавливают этот флаг.

MAPI_DIALOG

Отображает индикатор хода выполнения.

MAPI_MOVE

CopyProps должен выполнять операцию перемещения, а не операцию копирования. Если этот флаг не задан, copyProps выполняет операцию копирования.

MAPI_NOREPLACE

Существующие свойства в целевом объекте не должны быть перезаписаны. Если этот флаг не задан, CopyProps перезаписывает существующие свойства.

lppProblems

[вход, выход] На входных данных — указатель на указатель на структуру SPropProblemArray ; В противном случае — значение NULL, указывающее на отсутствие необходимости в информации об ошибке. Если lppProblems является допустимым указателем на входные данные, функция CopyProps возвращает подробные сведения об ошибках при копировании одного или нескольких свойств.

Возвращаемое значение

S_OK

Свойства успешно скопированы или перемещены.

MAPI_E_COLLISION

Не удается скопировать вложенный объект, так как в целевом объекте уже существует подобъект с тем же отображаемым именем, определенным свойством PR_DISPLAY_NAME (PidTagDisplayName).

MAPI_E_DECLINE_COPY

Поставщик услуг не реализует операцию копирования.

MAPI_E_FOLDER_CYCLE

Исходный объект, выполняющий операцию копирования или перемещения, прямо или косвенно содержит целевой объект. Значительная работа могла быть выполнена до обнаружения этого условия, поэтому исходные и целевые объекты могут быть частично изменены.

MAPI_E_INTERFACE_NOT_SUPPORTED

Интерфейс, определенный параметром lpInterface , не поддерживается целевым объектом.

MAPI_E_NO_ACCESS

Предпринята попытка доступа к объекту, для которого у вызывающего объекта недостаточно разрешений. Эта ошибка возвращается, если целевой объект совпадает с исходным объектом.

Следующие значения могут быть возвращены в структуре SPropProblemArray , но не в качестве возвращаемых значений для CopyProps. Эти ошибки относятся к одному свойству.

MAPI_E_BAD_CHARWIDTH

Либо флаг MAPI_UNICODE установлен, а CopyProps не поддерживает Юникод, либо MAPI_UNICODE не задан и CopyProps поддерживает только Юникод.

MAPI_E_COMPUTED

Свойство не может быть изменено вызывающим объектом, так как оно является свойством только для чтения, вычисляемым владельцем целевого объекта. Эта ошибка не является серьезной; вызывающий объект должен разрешить продолжение операции копирования.

MAPI_E_INVALID_TYPE

Недопустимый тип свойства.

MAPI_E_UNEXPECTED_TYPE

Тип свойства не является типом, ожидаемым вызывающим.

Замечания

Метод IMAPIProp::CopyProps копирует или перемещает выбранные свойства из текущего объекта в целевой объект. CopyProps используется главным образом для ответов на сообщения и их пересылки, когда только некоторые свойства исходного сообщения передаются с ответом или пересылаемой копией.

Все подобъекты в исходном объекте автоматически включаются в операцию и копируются или перемещаются целиком независимо от использования свойств, указанных структурой SPropTagArray . По умолчанию CopyProps перезаписывает все свойства в целевом объекте, которые соответствуют свойствам исходного объекта. Если какое-либо из скопированных или перемещенных свойств уже существует в целевом объекте, существующие свойства перезаписываются новыми свойствами, если флаг MAPI_NOREPLACE не установлен в параметре ulFlags . Существующие сведения в целевом объекте, который не перезаписан, остаются нетронутыми.

Примечания для исполнителей

Вы можете предоставить полную реализацию CopyProps или использовать реализацию, предоставляемую MAPI в объекте поддержки. Если вы хотите использовать реализацию MAPI, вызовите метод IMAPISupport::D oCopyProps . Однако если вы делегируете обработку в DoCopyProps и вам передан флаг MAPI_DECLINE_OK, избегайте вызова поддержки и возвращайте MAPI_E_DECLINE_COPY. MapI вызовет с этим флагом, чтобы избежать возможной рекурсии, которая может возникнуть при копировании папок.

Так как операция копирования может быть длительной, необходимо отобразить индикатор хода выполнения. Используйте реализацию IMAPIProgress , которая передается в параметре lpProgress , если она есть. Если lpProgress имеет значение NULL, вызовите метод IMAPISupport::D oProgressDialog , чтобы использовать реализацию MAPI.

Примечания для вызывающих методов

Не устанавливайте флаг MAPI_DECLINE_OK; он используется MAPI в вызовах реализаций CopyProps поставщика хранилища сообщений.

Так как операции копирования и перемещения могут занять время, целесообразно запросить отображение индикатора хода выполнения, установив флаг MAPI_DIALOG. Для параметра lpProgress можно задать свою реализацию IMAPIProgress, если она имеется, или значение NULL. Если lpProgress имеет значение NULL, CopyProps будет использовать индикатор хода выполнения по умолчанию, предоставляемый MAPI.

Вы можете подавить отображение индикатора хода выполнения, не устанавливая флаг MAPI_DIALOG. CopyProps игнорирует параметры ulUIParam и lpProgress и избегает отображения индикатора.

CopyProps может сообщать о глобальных и отдельных ошибках или ошибках, возникающих с одним или несколькими свойствами. Эти отдельные ошибки помещаются в структуру SPropProblemArray . Вы можете подавлять отчеты об ошибках на уровне свойства, передав значение NULL вместо допустимого указателя для параметра структуры массива проблем со свойством.

Если вы хотите получать сведения об ошибках, передайте допустимый указатель структуры SPropProblemArray в параметр lppProblems . Когда Функция CopyProps возвращает S_OK, проверка возможные ошибки с отдельными свойствами в структуре. Когда CopyProps возвращает ошибку, в структуре SPropProblemArray не возвращаются никакие сведения. Вместо этого вызовите метод IMAPIProp::GetLastError , чтобы получить подробные сведения об ошибке.

Если Функция CopyProps возвращает S_OK, освободите возвращенную структуру SPropProblemArray , вызвав функцию MAPIFreeBuffer .

При копировании свойств, уникальных для исходного типа объекта, необходимо убедиться, что целевой объект имеет тот же тип. CopyProps не запрещает связывать свойства, которые обычно принадлежат одному типу объектов, с другим типом объекта. Вы можете скопировать свойства, имеющие смысл для целевого объекта. Например, не следует копировать свойства сообщения в контейнер адресной книги.

Чтобы убедиться, что выполняется копирование между объектами одного типа, проверка, что исходный и целевой объекты имеют один и тот же тип путем сравнения указателей объектов или вызова метода IUnknown::QueryInterface. Задайте для идентификатора интерфейса, на который указывает lpInterface , стандартный интерфейс для исходного объекта. Кроме того, убедитесь, что свойство типа объекта или PR_OBJECT_TYPE (PidTagObjectType) совпадает с двумя объектами. Например, при копировании из сообщения задайте для lpInterface значение IID_IMessage, а PR_OBJECT_TYPE для обоих объектов — MAPI_MESSAGE.

Если в параметре lpDestObj передается недопустимый указатель, результаты будут непредсказуемыми.

Чтобы скопировать список получателей сообщения, вызовите метод CopyProps сообщения и включите свойство PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) в массив тегов свойств. Чтобы скопировать вложения сообщения, добавьте свойство PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments).

Чтобы скопировать иерархию или таблицу содержимого контейнера папки или адресной книги, включите свойства PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) или PR_CONTAINER_CONTENTS (PidTagContainerContents) в массив тегов свойств. Чтобы включить связанную таблицу содержимого папки, добавьте в массив свойство PR_FOLDER_ASSOCIATED_CONTENTS (PidTagFolderAssociatedContents).

Справочные материалы по MFCMAPI

Пример кода MFCMAPI указан в приведенной ниже таблице.

Файл	Функция	Comment
MAPIFunctions.cpp	CopyNamedProps	MFCMAPI использует метод IMAPIProp::CopyProps для копирования именованных свойств из одного сообщения в другое.
SingleMAPIPropListCtrl.cpp	CSingleMAPIPropListCtrl::OnPasteProperty	MFCMAPI использует метод IMAPIProp::CopyProps для вставки свойства, скопированного из другого объекта.