IABLogon::Advise
Область применения: Outlook 2013 | Outlook 2016
Регистрирует вызывающий объект для получения уведомлений о указанных событиях, влияющих на контейнер, пользователя сообщений или список рассылки.
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG FAR * lpulConnection
);
Параметры
cbEntryID
[в] Количество байтов в идентификаторе записи, на который указывает параметр lpEntryID .
lpEntryID
[в] Указатель на идентификатор записи объекта о том, какие уведомления должны быть созданы.
ulEventMask
[в] Битовая маска значений, указывающих типы событий уведомлений, которые нужны вызывающему объекту и должны быть включены в регистрацию. Существует соответствующая структура NOTIFICATION , связанная с каждым типом события, в котором содержатся сведения о событии. В следующей таблице перечислены допустимые значения для параметра ulEventMask и структуры, связанные с каждым значением.
| Тип события уведомления | Соответствующая структура NOTIFICATION |
|---|---|
|
fnevCriticalError |
ERROR_NOTIFICATION |
|
fnevObjectCreated |
OBJECT_NOTIFICATION |
|
fnevObjectDeleted |
OBJECT_NOTIFICATION |
|
fnevObjectModified |
OBJECT_NOTIFICATION |
|
fnevObjectCopied |
OBJECT_NOTIFICATION |
|
fnevObjectMoved |
OBJECT_NOTIFICATION |
lpAdviseSink
[в] Указатель на объект приемника рекомендаций для получения последующих уведомлений.
lpulConnection
[out] Указатель на ненулевое значение, представляющее регистрацию уведомления.
Возвращаемое значение
S_OK
Регистрация уведомления прошла успешно.
MAPI_E_INVALID_ENTRYID
Идентификатор записи, переданный в параметре lpEntryID , не имеет соответствующего формата.
MAPI_E_NO_SUPPORT
Поставщик адресной книги не поддерживает уведомление, возможно, потому, что он не позволяет вносить изменения в свои объекты.
MAPI_E_UNKNOWN_ENTRYID
Поставщик адресной книги не может обработать идентификатор записи, переданный в lpEntryID.
Замечания
Поставщики адресной книги реализуют метод IABLogon::Advise , чтобы зарегистрировать вызывающий объект для уведомления при изменении объекта в одном из контейнеров. Вызывающие пользователи могут зарегистрироваться для получения уведомлений о пользователях обмена сообщениями, списках рассылки или целых контейнерах.
Клиенты обычно вызывают метод IAddrBook::Advise , чтобы зарегистрироваться для получения уведомлений адресной книги. Затем MAPI вызывает метод Advise поставщика адресной книги, который отвечает за объект, представленный идентификатором записи в lpEntryID.
При изменении указанного объекта типа, представленного в ulEventMask, выполняется вызов метода OnNotify приемника рекомендаций, на который указывает lpAdviseSink. Данные, передаваемые в структуре NOTIFICATION в подпрограмму OnNotify , описывают это событие.
Примечания для исполнителей
Вы можете поддерживать уведомления с помощью MAPI или без нее. MAPI имеет три метода поддержки объектов, которые помогают поставщикам услуг реализовать уведомление:
Если вы решили использовать методы поддержки MAPI, вызовите команду Subscribe при вызове метода Advise и отпустите указатель lpAdviseSink .
Если вы решили самостоятельно поддерживать уведомление, вызовите метод AddRef приемника рекомендаций, представленного параметром lpAdviseSink , чтобы сохранить копию этого указателя. Сохраняйте эту копию до тех пор, пока метод IABLogon::Unadvise не будет вызван для отмены регистрации.
Независимо от того, как вы поддерживаете уведомление, назначьте номер ненулевого подключения регистрации уведомления и верните его в параметре lpulConnection . Не отпускайте этот номер подключения, пока не будет вызван метод Unadvise .
Примечания для вызывающих методов
Указатель приемника рекомендаций, который вы передаете в параметре lpAdviseSink в Совет , может указывать на объект, созданный вами или созданный MAPI с помощью функции HrThisThreadAdviseSink . Вы можете использовать HrThisThreadAdviseSink , если поддерживаете несколько потоков выполнения и хотите убедиться, что последующие вызовы метода OnNotify выполняются в соответствующее время в соответствующем потоке.
Будьте готовы к тому, что объект приемника рекомендаций будет освобожден в любое время после звонка в Совет и перед вызовом Unadvise. Поэтому следует освободить объект приемника рекомендаций после возврата Рекомендаций , если для него нет определенного долгосрочного использования.
Дополнительные сведения о процессе уведомления см. в разделе Уведомление о событиях в MAPI. Сведения об использовании методов IMAPISupport для поддержки уведомлений см. в разделе Поддержка уведомлений о событиях. Дополнительные сведения о многопоточности и MAPI см. в разделе Потоки в MAPI.