IMAPITable::Advise

Статья
04/04/2023

Область применения: Outlook 2013 | Outlook 2016

Регистрирует объект приемника рекомендаций для получения уведомлений о указанных событиях, влияющих на таблицу.

HRESULT Advise(
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG_PTR FAR * lpulConnection
);

Параметры

ulEventMask

[в] Значение, указывающее тип события, которое создаст уведомление. Допустимо только следующее значение:

fnevTableModified

lpAdviseSink

[в] Указатель на объект приемника рекомендаций для получения последующих уведомлений. Этот объект приемника рекомендаций должен быть уже выделен.

lpulConnection

[out] Указатель на ненулевое значение, представляющее успешную регистрацию уведомления.

Возвращаемое значение

S_OK

Регистрация уведомления успешно завершена.

MAPI_E_NO_SUPPORT

Реализация таблицы либо не поддерживает изменения строк и столбцов, либо не поддерживает уведомление.

Замечания

Используйте метод IMAPITable::Advise , чтобы зарегистрировать объект таблицы, реализованный в поставщике для обратных вызовов уведомлений. Всякий раз, когда происходит изменение объекта таблицы, поставщик проверяет, какой бит маски события был задан в параметре ulEventMask и, следовательно, какой тип изменения произошло. Если задан бит, поставщик вызывает метод IMAPIAdviseSink::OnNotify для объекта приемника рекомендаций , указанного параметром lpAdviseSink , чтобы сообщить о событии. Данные, передаваемые в структуре уведомлений в подпрограмму OnNotify , описывают событие.

Вызов OnNotify может происходить во время вызова, который изменяет объект, или в любое время. В системах, поддерживающих несколько потоков выполнения, вызов OnNotify может выполняться в любом потоке. Чтобы превратить вызов OnNotify , который может произойти в неподходящее время, в более безопасный для обработки, поставщик должен использовать функцию HrThisThreadAdviseSink .

Для предоставления уведомлений поставщик, реализующий Совет , должен сохранить копию указателя на объект приемника рекомендаций lpAdviseSink ; для этого он вызывает метод IUnknown::AddRef для приемника рекомендаций, чтобы сохранить указатель на объект до тех пор, пока регистрация уведомления не будет отменена вызовом метода IMAPITable::Unadvise . Реализация Рекомендаций должна назначить номер подключения регистрации уведомления и вызвать AddRef по этому номеру подключения, прежде чем возвращать его в параметре lpulConnection . Поставщики услуг могут освободить объект приемника рекомендаций до отмены регистрации, но они не должны освобождать номер подключения до вызова Unadvise .

После успешного вызова в Совет и до вызова Unadvise клиенты должны быть готовы к освобождению объекта приемника рекомендаций. Поэтому клиент должен освободить свой объект приемника рекомендаций после возврата Совет , если он не имеет для него определенное долгосрочное использование.

Из-за асинхронного поведения уведомлений реализации, изменяющие параметры столбца таблицы, могут получать уведомления с информацией, упорядоченной в предыдущем порядке столбцов. Например, строка таблицы может быть возвращена для сообщения, которое только что было удалено из контейнера. Такое уведомление отправляется при изменении параметра столбца и отправке сведений о нем, но представление таблицы уведомлений еще не обновлено с этой информацией.

Дополнительные сведения о процессе уведомления см. в разделе Уведомление о событиях в MAPI. Дополнительные сведения об уведомлениях таблицы см. в разделе Сведения об уведомлениях о таблицах. Сведения об использовании методов IMAPISupport для поддержки уведомлений см. в разделе Поддержка уведомлений о событиях.

Справочные материалы по MFCMAPI

Пример кода MFCMAPI указан в приведенной ниже таблице.

Файл	Функция	Comment
ContentsTableListCtrl.cpp	CContestTableListCtrl::NotificationOn	MFCMAPI использует метод IMAPITable::Advise для регистрации уведомлений, чтобы представление таблицы оставалось актуальным.

См. также

HrThisThreadAdviseSink
IMAPIAdviseSink::OnNotify
IMAPITable::Unadvise
TABLE_NOTIFICATION
IMAPITable: IUnknown MFCMAPI как пример кода

Поделиться через