IMAPIProp::SaveChanges

Статья
04/04/2023

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

Вносит постоянные изменения, внесенные в объект с момента последней операции сохранения.

HRESULT SaveChanges(
  ULONG ulFlags
);

Параметры

ulFlags

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

NON_EMS_XP_SAVE

Указывает, что сообщение не доставлено из Microsoft Exchange Server. Этот флаг следует использовать в сочетании с методом IMAPIFolder::CreateMessage и флагом ITEMPROC_FORCE, чтобы указать PST-хранилищу, что сообщение может обрабатываться правилами до того, как хранилище файлов личных папок (PST) уведомляет любой прослушивающий клиент о получении сообщения. Обработка правил применяется только к новым сообщениям, созданным с помощью IMAPIFolder::CreateMessage на сервере, который не является Exchange Server. В этом случае Exchange Server уже обработал бы правила для сообщения.

FORCE_SAVE

Изменения должны быть записаны в объект , переопределяя все предыдущие изменения, внесенные в объект, и объект должен быть закрыт. Для успешного выполнения операции необходимо задать разрешение на чтение и запись. Флаг FORCE_SAVE используется после того, как предыдущий вызов SaveChanges вернул MAPI_E_OBJECT_CHANGED.

KEEP_OPEN_READONLY

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

KEEP_OPEN_READWRITE

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

MAPI_DEFERRED_ERRORS

Позволяет saveChanges успешно вернуться, возможно, до полной фиксации изменений.

SPAMFILTER_ONSAVE

Включает фильтрацию нежелательной почты в сохраняемом сообщении. Поддержка фильтрации нежелательной почты доступна только в том случае, если тип адреса электронной почты отправителя соответствует протоколу SMTP, а сообщение сохранено в хранилище для файлов личных папок (PST).

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

S_OK

Приверженность изменениям была успешной.

MAPI_E_NO_ACCESS

SaveChanges не может держать объект открытым для разрешения только для чтения, если задано KEEP_OPEN_READONLY, или разрешение на чтение и запись, если задано KEEP_OPEN_READWRITE. Изменения не фиксируются.

MAPI_E_OBJECT_CHANGED

Объект изменился с момента его открытия.

MAPI_E_OBJECT_DELETED

Объект был удален с момента его открытия.

Замечания

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

Так как поставщикам служб не нужно создавать идентификатор записи для своих объектов, пока не будут сохранены все свойства, свойство объекта PR_ENTRYID (PidTagEntryId) может быть недоступно до вызова метода SaveChanges . Некоторые поставщики ожидают, пока в вызове SaveChanges не будет установлен флаг KEEP_OPEN_READONLY. KEEP_OPEN_READONLY указывает, что изменения, которые будут сохранены в текущем вызове, будут последними изменениями, которые будут внесены в объект .

Некоторые реализации хранилища сообщений не отображают новые сообщения в папке, пока клиент не сохранит изменения сообщения с помощью SaveChanges и не освободит объекты сообщений с помощью метода IUnknown::Release . Кроме того, некоторые реализации объектов не могут создать свойство PR_ENTRYID для вновь созданного объекта до тех пор, пока не будет вызван метод SaveChanges , а некоторые могут сделать это только после вызова SaveChanges с помощью KEEP_OPEN_READONLY, заданного в ulFlags.

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

Если вы получили флаг KEEP_OPEN_READONLY, вы можете оставить доступ к объекту для чтения и записи. Однако поставщик никогда не может оставить объект в состоянии только для чтения при передаче флага KEEP_OPEN_READWRITE.

Когда клиент сохраняет несколько вложений в несколько сообщений, он вызывает метод SaveChanges для каждого вложения и каждого сообщения. Часто клиенты задают MAPI_DEFERRED_ERRORS для каждого из этих вызовов, кроме последнего. Вы можете возвращать ошибки при последнем или более ранних вызовах. Флаг можно даже игнорировать.

Если KEEP_OPEN_READWRITE или KEEP_OPEN_READONLY заданы вместе с MAPI_DEFERRED_ERRORS, запрос на отсрочку ошибок можно игнорировать. Если MAPI_DEFERRED_ERRORS не задано в ulFlags, для вызова SaveChanges можно вернуть одну из ранее отложенных ошибок.

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

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

Если клиент передает KEEP_OPEN_READONLY, вызывает метод IMAPIProp::SetProps , а затем снова вызывает SaveChanges , то та же реализация может завершиться ошибкой.

После получения MAPI_E_NO_ACCESS от вызова, в котором вы задали KEEP_OPEN_READWRITE, вы по-прежнему будете иметь разрешение на чтение и запись для объекта . Вы можете снова вызвать SaveChanges , передав флаг KEEP_OPEN_READONLY или без флагов с KEEP_OPEN_SUFFIX.

То, поддерживает ли поставщик флаг KEEP_OPEN_READWRITE, зависит от реализации поставщика.

Чтобы указать, что единственным вызовом объекта после SaveChanges является IUnknown::Release, не устанавливайте флаги для параметра ulFlags . Ошибка из SaveChanges указывает, что не удалось сделать ожидающие изменения постоянными. Разные поставщики по-разному обрабатывают отсутствие флагов при вызове SaveChanges . Некоторые поставщики обрабатывают это состояние так же, как KEEP_OPEN_READONLY; другие поставщики интерпретируют его так же, как и KEEP_OPEN_READWRITE. Другие поставщики завершают работу объекта, если не получают флаги при вызове SaveChanges .

Некоторые свойства, обычно вычисляемые свойства, не могут быть обработаны до тех пор, пока вы не вызовете SaveChanges , а в некоторых случаях — Release.

При внесении массовых изменений, таких как сохранение вложений в несколько сообщений, отложите обработку ошибок, установив флаг MAPI_DEFERRED_ERRORS в ulFlags. При сохранении нескольких вложений в несколько сообщений выполните один вызов SaveChanges для каждого вложения и один вызов SaveChanges для каждого сообщения. Установите флаг MAPI_DEFERRED_ERRORS для каждого вызова вложения и для всех сообщений, кроме последнего.

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

Вы не можете вызвать SaveChanges с флагом FORCE_SAVE для удаленного открытого объекта.

Если SaveChanges возвращает ошибку, объект, изменения которого должны были быть сохранены, остается открытым независимо от флагов, заданных в параметре ulFlags .

Важно!

UlFlags NON_EMS_XP_SAVE и SPAMFILTER_ONSAVE могут не быть определены в текущем загружаемом файле заголовка. В этом случае его можно добавить в код, используя следующие значения:#define SPAMFILTER_ONSAVE ((ULONG) 0x00000080)>#define NON_EMS_XP_SAVE ((ULONG) 0x00001000)

Дополнительные сведения см. в разделе Сохранение свойств MAPI.

См. также

IMAPIProp::SetProps
Каноническое свойство PidTagEntryId
IMAPIProp : IUnknown сохранение свойств MAPI

Поделиться через