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