IMAPISupport::DoCopyProps

Статья
04/04/2023

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

Копирует или перемещает одно или несколько свойств объекта в другой объект.

HRESULT DoCopyProps(
  LPCIID lpSrcInterface,
  LPVOID lpSrcObj,
  LPSPropTagArray lpIncludeProps,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  LPCIID lpDestInterface,
  LPVOID lpDestObj,
  ULONG ulFlags,
  LPSPropProblemArray FAR * lppProblems
);

Параметры

lpSrcInterface

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

lpSrcObj

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

lpIncludeProps

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

ulUIParam

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

lpProgress

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

lpDestInterface

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

lpDestObj

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

ulFlags

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

MAPI_DIALOG

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

MAPI_MOVE

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

MAPI_NOREPLACE

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

lppProblems

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

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

S_OK

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

MAPI_E_COLLISION

Свойство для копирования или перемещения уже существует в целевом объекте, и установлен флаг MAPI_NOREPLACE.

MAPI_E_FOLDER_CYCLE

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

MAPI_E_INTERFACE_NOT_SUPPORTED

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

MAPI_E_NO_ACCESS

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

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

MAPI_E_BAD_CHARWIDTH

Флаг MAPI_UNICODE установлен, и DoCopyProps не поддерживает Юникод, или MAPI_UNICODE не задан и DoCopyProps поддерживает только Юникод.

MAPI_E_COMPUTED

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

MAPI_E_INVALID_TYPE

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

MAPI_E_UNEXPECTED_TYPE

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

Замечания

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

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

При копировании свойств между объектами одного типа, например двумя сообщениями, параметры lpSrcInterface и lpDestInterface должны содержать одинаковый идентификатор интерфейса, а параметры lpSrcObj и lpDestObj должны указывать на объекты одного типа. Если lpDestInterface имеет значение NULL, DoCopyProps возвращает MAPI_E_INVALID_PARAMETER. Если задать для lpDestInterface допустимый идентификатор интерфейса, а для lpDestObj — недопустимый указатель, результаты будут непредсказуемыми. Скорее всего, поставщик завершится ошибкой.

Установите флаг MAPI_NOREPLACE, если вы не хотите, чтобы какие-либо свойства в целевом объекте были перезаписаны. Свойства в целевом объекте, существующие в исходном объекте и не перезаписанные, не удаляются и не изменяются.

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

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

При копировании или перемещении вложенных папок их содержимое копируется или перемещается целиком независимо от использования свойств, указанных структурой SPropTagArray .

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

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

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