IMSLogon::Advise
Область применения: Outlook 2013 | Outlook 2016
Регистрирует объект у поставщика хранилища сообщений для уведомлений об изменениях в хранилище сообщений. Затем хранилище сообщений будет отправлять уведомления об изменениях зарегистрированного объекта.
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG FAR * lpulConnection
);
Параметры
cbEntryID
[в] Размер (в байтах) идентификатора записи, на который указывает параметр lpEntryID .
lpEntryID
[в] Указатель на идентификатор записи объекта о том, какие уведомления должны быть созданы. Это может быть папка, сообщение или любой другой объект в хранилище сообщений. Кроме того, если MAPI задает для параметра cbEntryID значение 0 и передает значение NULL для lpEntryID, приемник рекомендаций предоставляет уведомления об изменениях для всего хранилища сообщений.
ulEventMask
[в] Маска событий типов событий уведомлений, происходящих для объекта, о котором MAPI будет создавать уведомления. Маска фильтрует определенные случаи. Каждый тип события имеет связанную с ним структуру, которая содержит дополнительные сведения о событии. В следующей таблице перечислены возможные типы событий, а также соответствующие структуры.
Тип события уведомления | Соответствующая структура |
---|---|
fnevCriticalError |
ERROR_NOTIFICATION |
fnevNewMail |
NEWMAIL_NOTIFICATION |
fnevObjectCreated |
OBJECT_NOTIFICATION |
fnevObjectDeleted |
OBJECT_NOTIFICATION |
fnevObjectModified |
OBJECT_NOTIFICATION |
fnevObjectCopied |
OBJECT_NOTIFICATION |
fnevObjectMoved |
OBJECT_NOTIFICATION |
fnevSearchComplete |
OBJECT_NOTIFICATION |
fnevStatusObjectModified |
STATUS_OBJECT_NOTIFICATION |
lpAdviseSink
[в] Указатель на объект приемника рекомендаций, вызываемый при возникновении события для объекта сеанса о том, какое уведомление было запрошено. Этот объект приемника рекомендаций уже должен существовать.
lpulConnection
[out] Указатель на переменную, которая после успешного возврата содержит номер подключения для регистрации уведомления. Номер подключения должен быть ненулевым.
Возвращаемое значение
S_OK
����� ������� � ������ ��������� ��������� ��� ��������.
MAPI_E_NO_SUPPORT
Операция не поддерживается MAPI или одним или несколькими поставщиками услуг.
Замечания
Поставщики хранилища сообщений реализуют метод IMSLogon::Advise , чтобы зарегистрировать объект для обратных вызовов уведомлений. При каждом изменении указанного объекта поставщик проверяет, какой бит маски события был задан в параметре ulEventMask , и, следовательно, какой тип изменения произошло. Если задан бит, поставщик вызывает метод IMAPIAdviseSink::OnNotify для объекта приемника рекомендаций, указанного параметром lpAdviseSink , чтобы сообщить о событии. Данные, передаваемые в структуре уведомлений в подпрограмму OnNotify , описывают событие.
Вызов OnNotify может произойти во время вызова, который изменяет объект, или в любое время позже. В системах, поддерживающих несколько потоков выполнения, вызов OnNotify может выполняться в любом потоке. Чтобы безопасно обработать вызов OnNotify , который может произойти в неподходящее время, клиентское приложение должно использовать функцию HrThisThreadAdviseSink .
Для предоставления уведомлений поставщик хранилища сообщений, реализующий Совет, должен сохранить копию указателя на объект приемника рекомендаций lpAdviseSink . Для этого поставщик вызывает метод IUnknown::AddRef для приемника рекомендаций, чтобы сохранить указатель объекта до тех пор, пока регистрация уведомления не будет отменена с помощью вызова метода IMSLogon::Unadvise . Реализация Рекомендаций должна назначить номер подключения регистрации уведомления и вызвать AddRef по этому номеру подключения, прежде чем возвращать его в параметре lpulConnection . Поставщики услуг могут освободить объект приемника рекомендаций до отмены регистрации, но они не должны освобождать номер подключения до вызова Unadvise .
После успешного вызова в Совет и до вызова Unadvise поставщики должны быть подготовлены к освобождению объекта приемника рекомендаций. Таким образом, поставщик должен освободить свой объект приемника рекомендаций после возврата Рекомендаций , если он не имеет для него определенное долгосрочное использование.
Дополнительные сведения о процессе уведомления см. в разделе Уведомление о событиях в MAPI.