IMAPIProp::CopyTo

Статья
04/04/2023

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

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

HRESULT CopyTo(
 ULONG ciidExclude,
 LPCIID rgiidExclude,
 LPSPropTagArray lpExcludeProps,
 ULONG_PTR ulUIParam,
 LPMAPIPROGRESS lpProgress,
 LPCIID lpInterface,
 LPVOID lpDestObj,
 ULONG ulFlags,
 LPSPropProblemArray FAR * lppProblems
);

Параметры

ciidExclude

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

rgiidExclude

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

lpExcludeProps

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

ulUIParam

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

lpProgress

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

lpInterface

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

lpDestObj

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

ulFlags

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

MAPI_DECLINE_OK

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

MAPI_DIALOG

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

MAPI_MOVE

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

MAPI_NOREPLACE

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

lppProblems

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

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

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 , но не в качестве возвращаемых значений для CopyTo. Следующие ошибки применяются к одному свойству:

MAPI_E_BAD_CHARWIDTH

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

MAPI_E_COMPUTED

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

MAPI_E_INVALID_TYPE

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

MAPI_E_UNEXPECTED_TYPE

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

Замечания

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

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

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

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

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

Не пытайтесь задать в целевом объекте какие-либо известные свойства, доступные только для чтения; вместо этого возвращает MAPI_E_NO_ACCESS.

Исходный и целевой объекты должны использовать одни и те же интерфейсы. Возвращает MAPI_E_INVALID_PARAMETER, если lpInterface не задан.

Возвращает MAPI_E_INTERFACE_NOT_SUPPORTED, если все известные интерфейсы исключены.

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

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

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

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

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

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

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

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

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

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

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

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

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

PROP_TAG(PT_LONG, 0x8002)

Тег свойства PR_NULL (PidTagNull) не может быть включен в массив lpExcludeProps .

Полезность функции CopyTo для исключения интерфейсов, возможно, не столь очевидна, как полезность исключения свойств. Интерфейс можно исключить при копировании в объект, которому не известно о группе свойств. Например, если вы копируете свойства из папки во вложение, единственными свойствами, с которыми может работать вложение, являются универсальные свойства, доступные в любой реализации IMAPIProp . Если исключить IMAPIFolder из операции копирования, вложение не получит ни одного из более конкретных свойств папки.

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

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

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

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

Файл	Функция	Comment
File.cpp	LoadFromMSG	MFCMAPI использует метод IMAPIProp::CopyTo для копирования свойств из файла .msg в объект IMAPIMessageSite .
FolderDlg.cpp	CFolderDlg::HandlePaste	MFCMAPI использует метод IMAPIProp::CopyTo для копирования свойств из исходного сообщения в целевое сообщение во время операции вставки.