Уведомление о событиях в MAPI
Область применения: Outlook 2013 | Outlook 2016
Уведомление о событиях — это обмен информацией между двумя объектами MAPI. Через один из объектов клиент или поставщик услуг регистрируется для уведомления об изменении или ошибке, называемом событием, которое может произойти в другом объекте. После возникновения события первый объект получает уведомление об изменении или ошибке. Объект, получая уведомление, называется приемником рекомендаций; Объект, отвечающий за уведомление, называется источником рекомендаций.
Существует три типа объектов приемника рекомендаций (все типы являются стандартными объектами MAPI):
- Советы по объектам приемника.
- Объекты-приемники с рекомендацией формы.
- Просмотр объектов приемника рекомендаций.
Объекты приемника рекомендаций являются наиболее распространенным типом. Приемники рекомендаций обычно реализуются клиентскими приложениями для получения уведомлений об адресной книге и хранилище сообщений, а также для поддержки интерфейса IMAPIAdviseSink : IUnknown . IMAPIAdviseSink содержит один метод IMAPIAdviseSink::OnNotify. Приемники рекомендаций по форме и представлению являются менее распространенными; они реализуются для получения уведомлений об изменениях в пользовательских формах. Приемники рекомендаций формы поддерживают интерфейс IMAPIFormAdviseSink: интерфейс IUnknown и приемники рекомендаций представления поддерживают интерфейс IMAPIViewAdviseSink : IUnknown . Так как большинство клиентов реализуют стандартные объекты приемника рекомендаций, предполагается, что обсуждения уведомлений связаны с адресной книгой и хранилищем сообщений, а не с уведомлениями форм. Дополнительные сведения об уведомлениях о формах см. в разделах MAPI Forms Notifications and Writing Form Server Code.
Рекомендуется реализовать исходные объекты поставщиками услуг и MAPI. Не все поставщики услуг поддерживают уведомление о событиях; это необязательно, но настоятельно рекомендуется. Поставщики хранилищ сообщений и адресных книг обычно поддерживают уведомления об объектах для нескольких объектов и табличные уведомления о содержимом и таблицах иерархии. Поставщики транспорта не поддерживают уведомления напрямую; они полагаются на альтернативные методы связи с клиентами.
В отличие от приемников рекомендаций, исходные объекты рекомендаций не являются уникальным типом объекта MAPI. Многие объекты MAPI, такие как хранилища сообщений и таблицы, могут взять на себя роль источника рекомендаций. Источник рекомендаций — это любой объект MAPI, который выполняет следующие действия:
Реализует метод Рекомендации для получения регистраций уведомлений.
Реализует метод Unadvise для получения отмены уведомлений.
Создает уведомления соответствующего типа для соответствующих объектов приемников рекомендаций, зарегистрированных путем вызова их методов IMAPIAdviseSink::OnNotify .
Клиенты, которые реализуют объекты приемника рекомендаций, вызывают Совет , когда они хотят зарегистрироваться для получения уведомления, в большинстве случаев передает идентификатор записи объекта, с которым должна произойти регистрация, и отменяет, когда они хотят отменить регистрацию. Клиенты передают параметр Совету , который указывает, какие из нескольких типов событий они хотят отслеживать. Совет возвращает ненулевое число, представляющее успешное соединение между приемником рекомендаций и источником рекомендаций.
Перед вызовом Совет клиенты могут определить, поддерживает ли поставщик хранилища сообщений уведомление, проверив, что флаг STORE_NOTIFY_OK установлен в свойстве PR_STORE_SUPPORT_MASK хранилища сообщений (PidTagStoreSupportMask). Клиенты не могут заранее определить, поддерживает ли поставщик адресной книги уведомления. Клиенты должны попытаться зарегистрироваться, и если попытка завершается неудачей, они могут предположить, что уведомления не поддерживаются.
При возникновении события, для которого зарегистрирован клиент, источник рекомендаций уведомляет приемник рекомендаций, вызывая его метод IMAPIAdviseSink::OnNotify со структурой данных уведомления, содержащей сведения о событии. Реализация OnNotify приемника рекомендаций может выполнять задачи в ответ на уведомление, такие как обновление данных в памяти или обновление экрана.
Поставщики услуг могут реализовать поддержку уведомлений вручную или воспользоваться преимуществами справки, предоставляемой тремя методами IMAPISupport::Subscribe, IMAPISupport::Unsubscribe и IMAPISupport::Notify. Методы подписки и отмены подписки обрабатывают регистрацию и отмену регистрации уведомлений для поставщиков; При необходимости метод Notify обрабатывает отправку уведомлений.
Чтобы использовать методы объектов поддержки для регистрации уведомлений, поставщики услуг вызывают IMAPISupport::Subscribe в своих методах Рекомендаций и передают в пункт Подписаться на указатель приемника рекомендаций, который клиенты передают в Совет. Если идентификатор записи передается в качестве входного параметра для указания источника рекомендаций, поставщики услуг преобразуют его в двоичный ключ. Подписка создает уникальный номер подключения, и именно этот номер поставщики услуг возвращают клиентам. Поставщики услуг могут освободить указатель объекта приемника рекомендаций клиента в любое время после завершения вызова Рекомендации .
Когда клиенты вызывают Unadvise для отмены регистрации, поставщики услуг либо уменьшают количество ссылок на указатель приемника рекомендаций клиента, либо вызывают отмену подписки , чтобы сделать то же самое.
Когда нужно создать уведомление, поставщики услуг выполняют внутреннюю обработку, связанную с уведомлением, и инициализирует структуру УВЕДОМЛЕНИЯ , задавая для всех его неиспользуемых членов значение нулю. Этот метод инициализации структуры NOTIFICATION может помочь клиентам создавать меньшие, быстрые и менее подверженные ошибкам реализации OnNotify .
На следующем рисунке показана связь между объектами приемника рекомендаций, исходными объектами рекомендаций и MAPI. MAPI используется только в том случае, если источник рекомендаций вызывает методы IMAPISupport для поддержки уведомлений.
Вызовы уведомлений о событии
Класс MFCMAPI CAdviseSink (с использованием файлов AdviseSink.h и AdviseSink.cpp) реализует объект приемника рекомендаций для всех вызовов к Совету. Дополнительные сведения о MFCMAPI см. в разделах MFCMAPI как пример кода и MFCMAPI.