IMAPISession::Advise
Область применения: Outlook 2013 | Outlook 2016
Регистрируется для получения уведомлений о указанных событиях, влияющих на сеанс.
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG_PTR lpulConnection
);
Параметры
cbEntryID
[в] Число байтов в идентификаторе записи, на который указывает параметр lpEntryID .
lpEntryID
[в] Указатель на идентификатор записи адресной книги или объекта хранилища сообщений о том, какие уведомления должны быть созданы, или значение NULL, указывающее, что клиент регистрируется для получения уведомлений о событиях, влияющих только на сеанс.
ulEventMask
[в] Маска значений, указывающих типы событий уведомлений, которые интересуют клиента и которые должны быть включены в регистрацию. Если lpEntryID имеет значение NULL, MAPI автоматически регистрирует клиент для критических событий ошибок, влияющих только на сеанс. Если lpEntryID указывает на идентификатор записи, для параметра ulEventMask допустимы следующие значения:
fnevCriticalError
Регистрирует уведомления о серьезных ошибках, таких как нехватка памяти.
fnevExtended
Регистрирует уведомления о событиях, относящихся к определенной адресной книге или поставщику хранилища сообщений, и о завершении сеанса.
fnevNewMail
Регистрирует уведомления о поступлении новых сообщений.
fnevObjectCreated
Регистрирует уведомления о создании нового объекта.
fnevObjectCopied
Регистрирует уведомления о копируемом объекте.
fnevObjectDeleted
Регистрирует уведомления об удалении объекта.
fnevObjectModified
Регистрирует уведомления об изменении объекта.
fnevObjectMoved
Регистрирует уведомления о перемещении объекта.
fnevSearchComplete
Регистрирует уведомления о завершении операции поиска.
lpAdviseSink
[в] Указатель на объект приемника рекомендаций для получения последующих уведомлений. Этот объект приемника рекомендаций должен быть уже выделен.
lpulConnection
[out] Указатель на ненулевое число, представляющее соединение между объектом приемника рекомендаций вызывающего объекта и сеансом.
Возвращаемое значение
S_OK
Регистрация прошла успешно.
MAPI_E_INVALID_ENTRYID
Идентификатор записи, на который указывает lpEntryID , не представляет допустимый идентификатор записи.
MAPI_E_NO_SUPPORT
Поставщик услуг, отвечающий за идентификатор записи, на который указывает lpEntryID , либо не поддерживает тип событий, указанный в параметре ulEventMask , либо не поддерживает уведомление.
MAPI_E_UNKNOWN_ENTRYID
Идентификатор записи, на который указывает lpEntryID , не может обрабатываться ни одной из поставщиков услуг в профиле.
Замечания
Метод IMAPISession::Advise устанавливает соединение между объектом приемника рекомендаций вызывающего объекта, сеансом и, при необходимости, поставщиком услуг. Это подключение используется для отправки уведомлений в приемник рекомендаций, когда одно или несколько событий, указанных в параметре ulEventMask , происходят с объектом, на который указывает lpEntryID. Если lpEntryID имеет значение NULL, целевой объект — это сеанс, а уведомления отправляются только о критических ошибках и расширенных событиях.
Если lpEntryID указывает на допустимый идентификатор записи, MAPI вызывает метод Advise объекта входа, который принадлежит ответственному поставщику услуг. Например, если lpEntryID указывает на идентификатор записи списка рассылки, MAPI вызывает метод IABLogon::Advise соответствующего поставщика адресной книги.
Чтобы отправить уведомление, поставщик услуг или MAPI вызывает метод IMAPIAdviseSink::OnNotify зарегистрированного приемника рекомендаций. Один из параметров onNotify, структура уведомлений, содержит сведения, описывающие конкретное событие.
Примечания для вызывающих методов
В системах, поддерживающих несколько потоков выполнения, вызов OnNotify также может выполняться в любом потоке в любое время. Если требуется убедиться, что уведомления будут появляться только в определенное время в определенном потоке, вызовите функцию HrThisThreadAdviseSink , чтобы создать объект приемника рекомендаций, который передается методу Advise .
Чтобы определить, когда клиент выключился, зарегистрируйтесь для получения уведомлений в поставщике услуг, вызвав Команду "Совет" , для параметра lpEntryID задано значение NULL, а для параметра cbEntryID — значение 0. При выходе из системы вы получите уведомление fnevExtended.
После успешного вызова к Совету и до вызова IMAPISession::Unadvise для отмены регистрации отпустите объект приемника рекомендаций, если для него нет определенного долгосрочного использования.
Общие сведения о процессе уведомления см. в разделе Уведомление о событиях в MAPI.
Дополнительные сведения об обработке уведомлений см. в разделе Обработка уведомлений.
Справочные материалы по MFCMAPI
Пример кода MFCMAPI указан в приведенной ниже таблице.
| Файл | Функция | Comment |
|---|---|---|
| BaseDialog.cpp |
CBaseDialog::OnNotificationsOn |
MFCMAPI использует метод IMAPISession::Advise для регистрации уведомлений для сеанса. |