Поддержка уведомлений о событиях
Область применения: Outlook 2013 | Outlook 2016
Так как поддержка уведомлений о событиях может быть сложной, MAPI предоставляет три метода поддержки объектов, которые реализуют наиболее сложные части процесса. Эти методы работают как единое целое, и поставщик должен использовать все три или ни один из них.
Методы поддержки MAPI используют ключи уведомлений для управления подключениями между приемниками рекомендаций и объектами, которые создают уведомления. Ключ уведомления — это структура NOTIFKEY , содержащая двоичные данные, которые идентифицируют объект в разных процессах. Ключ уведомления обычно копируется из долгосрочного идентификатора записи исходного объекта advise. Если клиент предоставил идентификатор записи в вызове рекомендации, его можно использовать для ключа уведомления. Если параметр lpEntryIDдля свойства Advise имеет значение NULL, используйте идентификатор записи самого внешнего возможного объекта контейнера, например хранилища сообщений.
Чтобы использовать методы поддержки, вызывайте IMAPISupport::Subscribe всякий раз, когда клиент вызывает метод Совет , чтобы зарегистрироваться для получения уведомления. Выделите структуру NOTIFKEY и создайте уникальный ключ уведомления для исходного объекта рекомендаций. Например, поставщик хранилища сообщений, которому предлагается уведомить клиента о получении сообщения в определенную папку, создает ключ уведомления для этой папки. Передайте указатель на структуру NOTIFKEY в вызове Подписки вместе с указателем на приемник рекомендаций клиента. Подписка вызывает метод IUnknown::AddRef приемника рекомендаций для увеличения числа ссылок, а MAPI сохраняет указатель до отмены регистрации.
Флаг NOTIFY_SYNC можно передать в поле Подписаться , чтобы запросить, что уведомление ведет себя синхронно и не возвращается до тех пор, пока не будут выполнены все вызовы методов IMAPIAdviseSink::OnNotify зарегистрированных приемников рекомендаций. Установите этот флаг только для внутреннего использования. Не устанавливайте его при ответе на вызов клиента Посоветовать . Уведомление о событиях между клиентами и поставщиками всегда асинхронно. То есть MAPI гарантирует, что вызов, во время которого происходит событие, будет возвращен клиенту до выполнения любого из вызовов OnNotify .
Если вы задали флаг NOTIFY_SYNC, не вносите никаких изменений ни в один из объектов приемника рекомендаций и не передайте приемник рекомендаций оболочки, созданный HrThisThreadAdviseSink , в подписку. HrThisThreadAdviseSink создает потокобезопасную версию приемника рекомендаций для использования только с асинхронным уведомлением.
Если приемник рекомендаций, зарегистрированный для синхронного уведомления, возвращается из OnNotify с установленным флагом CALLBACK_DISCONTINUE, IMAPISupport::Notify задает флаг NOTIFY_CANCELED и возвращает без вызовов OnNotify.
После возврата подписки вам больше не придется держаться за копию приемника рекомендаций клиента. Вызовите метод IUnknown::Release , чтобы освободить его. Подписка возвращает ненулевой номер подключения, который необходимо вернуть клиенту. Номер подключения представляет связь между источником рекомендаций и приемником рекомендаций. Он остается действительным до тех пор, пока клиент не сделает успешный вызов Unadvise.
Когда клиент будет готов отменить регистрацию, он вызывает метод Unadvise . Передайте номер подключения из вызова Unadvise в IMAPISupport::Unsubscribe. Отмена подписки вызывает метод IUnknown::Release приемника рекомендаций . Как и в случае с советом и отменой подписки, вызовы подписки и отмены подписки должны быть сопряженными. Необходимо выполнить один вызов отмены подписки для каждого вызова, который выполняется для подписки. Однако вам не нужно вызывать подписку при каждом вызове метода Advise . И наоборот, его можно вызвать для настройки внутренних уведомлений.
При возникновении события выделите одну или несколько структур NOTIFICATION типа, подходящего для события, и вызовите IMAPISupport::Notify. Уведомление создает уведомление для каждого зарегистрированного приемника рекомендаций. Необходимо задать для всех неиспользуемых элементов структуры NOTIFICATION значение нулю. Этот метод инициализации структуры NOTIFICATION может помочь клиентам создавать меньшие, быстрые и менее подверженные ошибкам реализации OnNotify .
Обратите внимание, что для каждого события требуется отдельная структура NOTIFICATION , даже для нескольких событий одного типа. Например, если три клиента зарегистрированы для уведомления таблицы в определенной таблице и в нее добавляются пять строк, необходимо создать пять OBJECT_NOTIFICATION структур для вызова Notify . Такое пакетное уведомление приводит к повышению производительности по сравнению с вызовом Notify пять раз. Для каждого вызова Notify MAPI вызывает метод IMAPIAdviseSink::OnNotify каждого зарегистрированного приемника рекомендаций. Если зарегистрированных приемников рекомендаций нет, MAPI игнорирует вызов.
Поставщики услуг, отправляющие пакетные уведомления, должны упорядочить их, чтобы их можно было интерпретировать от первого уведомления до последнего. Такое упорядочение особенно необходимо, если пакет уведомлений содержит ряд событий, например TABLE_ROW_ADDED с одним событием, ссылающимся на предыдущей строке, добавленной в другое событие в том же пакете.