IMAPISupport::DoCopyTo

Статья
04/04/2023

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

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

HRESULT DoCopyTo(
  LPCIID lpSrcInterface,
  LPVOID lpSrcObj,
  ULONG ciidExclude,
  LPCIID rgiidExclude,
  LPSPropTagArray lpExcludeProps,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  LPCIID lpDestInterface,
  LPVOID lpDestObj,
  ULONG ulFlags,
  LPSPropProblemArray FAR * lppProblems
);

Параметры

lpSrcInterface

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

lpSrcObj

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

ciidExclude

[в] Количество интерфейсов, исключаемых при копировании или перемещении свойств.

rgiidExclude

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

lpExcludeProps

[в] Указатель на массив тегов свойств, который определяет теги свойств, которые должны быть исключены из операции копирования или перемещения. Передача NULL в параметре lpExcludeProps означает, что все свойства объекта должны быть скопированы или перемещены. DoCopyTo возвращает MAPI_E_INVALID_PARAMETER, когда элемент cValues структуры SPropTagArray , на который указывает lpExcludeProps , имеет значение 0.

ulUIParam

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

lpProgress

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

lpDestInterface

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

lpDestObj

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

ulFlags

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

MAPI_DIALOG

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

MAPI_MOVE

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

MAPI_NOREPLACE

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

lppProblems

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

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

S_OK

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

MAPI_E_COLLISION

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

MAPI_E_FOLDER_CYCLE

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

MAPI_E_INTERFACE_NOT_SUPPORTED

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

MAPI_E_NO_ACCESS

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

MAPI_E_INVALID_PARAMETER

Параметр lpSrcInterface имеет значение NULL.

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

MAPI_E_BAD_CHARWIDTH

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

MAPI_E_COMPUTED

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

MAPI_E_INVALID_TYPE

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

MAPI_E_UNEXPECTED_TYPE

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

Замечания

Метод IMAPISupport::D oCopyTo реализован для объектов поддержки поставщика хранилища сообщений. Поставщики хранилища сообщений могут вызывать DoCopyTo для реализации метода IMAPIProp::CopyTo для своих папок и сообщений.

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

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

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

Чтобы исключить свойства из операции копирования или перемещения, включите их теги свойств в параметр lpExcludeProps . Если передать результаты использования макроса PROP_TAG для создания тега свойства на основе определенного идентификатора в массиве тегов свойств, все свойства с этим идентификатором будут исключены. Например, следующая запись в массиве тегов свойств приводит к исключению всех свойств с идентификатором 0x8002 независимо от типа:

PROP_TAG(PT_LONG, 0x8002)

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

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

Игнорируйте MAPI_E_COMPUTED ошибки, возвращаемые в структуре SPropProblemArray в параметре lppProblems .

Идентификатор интерфейса, на который указывает lpSrcInterface , обычно совпадает с идентификатором интерфейса, на который указывает lpDestInterface .

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

И наоборот, если вам известно о дополнительных сведениях, которые не следует копировать или перемещать, добавьте идентификаторы интерфейса для интерфейсов, которые должны быть исключены в массиве, переданном в параметре rgiidExclude . Например, если вы копируете сообщения, но не какие-либо из их вложений, передайте IID_IMessage в массив rgiidExclude . DoCopyTo игнорирует все интерфейсы, перечисленные в rgiidExclude , которые не распознаются.

При использовании параметра rgiidExclude для исключения интерфейса он также исключает все интерфейсы, производные от этого интерфейса. Например, исключение интерфейса IMAPIContainer приводит к исключению папок или контейнеров адресной книги в зависимости от типа поставщика. Не исключайте IMAPIProp или IUnknown , так как на их основе наследуется так много интерфейсов.

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

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

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

Если при вызове DoCopyTo возникает глобальная ошибка, не используйте или не освобождайте структуру SPropProblemArray . Поставщики должны игнорировать элемент ulIndex в структурах SPropProblemArray , возвращенных DoCopyTo.