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


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.

См. также

HrThisThreadAdviseSink

IMAPIAdviseSink::OnNotify

IMSLogon::Unadvise

�����������

IMSLogon : IUnknown