IMsgStore::Advise
Область применения: Outlook 2013 | Outlook 2016
Регистрируется для получения уведомлений о указанных событиях, влияющих на хранилище сообщений.
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG_PTR lpulConnection
);
Параметры
cbEntryID
[в] Число байтов в идентификаторе записи, на который указывает параметр lpEntryID .
lpEntryID
[в] Указатель на идентификатор записи папки или сообщения о том, какие уведомления должны быть созданы, или значение NULL. Если для lpEntryID задано значение NULL, функция "Совет" регистрирует уведомления во всем хранилище сообщений.
ulEventMask
[в] Маска значений, указывающих типы событий уведомлений, которые нужны вызывающему объекту и должны быть включены в регистрацию. Существует соответствующая структура NOTIFICATION , связанная с каждым типом события, в котором содержатся сведения о событии. Ниже приведены допустимые значения для параметра ulEventMask .
fnevCriticalError
Регистрирует уведомления о серьезных ошибках, таких как нехватка памяти.
fnevExtended
Регистрирует уведомления о событиях, относящихся к конкретному поставщику хранилища сообщений.
fnevNewMail
Регистрирует уведомления о поступлении новых сообщений.
fnevObjectCreated
Регистрируется для уведомлений о создании новой папки или сообщения.
fnevObjectCopied
Регистрирует уведомления о копируемой папке или сообщении.
fnevObjectDeleted
Регистрирует уведомления об удалении папки или сообщения.
fnevObjectModified
Регистрирует уведомления об изменении папки или сообщения.
fnevObjectMoved
Регистрирует уведомления о перемещении папки или сообщения.
fnevSearchComplete
Регистрирует уведомления о завершении операции поиска.
lpAdviseSink
[в] Указатель на объект приемника рекомендаций для получения последующих уведомлений. Этот объект приемника рекомендаций должен быть уже выделен.
lpulConnection
[out] Указатель на ненулевое число, представляющее соединение между объектом приемника рекомендаций вызывающего объекта и сеансом.
lpAdviseSink
[в] Указатель на объект приемника рекомендаций для получения последующих уведомлений. Этот объект приемника рекомендаций должен быть уже выделен.
lpulConnection
[out] Указатель на ненулевой номер подключения, представляющий соединение между объектом приемника рекомендаций вызывающего объекта и хранилищем сообщений.
Возвращаемое значение
S_OK
Регистрация прошла успешно.
MAPI_E_NO_SUPPORT
Поставщик хранилища сообщений не поддерживает регистрацию уведомлений через хранилище сообщений.
Замечания
Метод IMsgStore::Advise устанавливает связь между объектом приемника рекомендаций вызывающего объекта и хранилищем сообщений или объектом в хранилище сообщений. Это подключение используется для отправки уведомлений в приемник рекомендаций, когда одно или несколько событий, указанных в параметре ulEventMask , происходят с исходным объектом advise. Если параметр lpEntryID указывает на допустимый идентификатор записи, источником рекомендаций является объект, идентифицируемый этим идентификатором записи. Если lpEntryID имеет значение NULL, источником рекомендаций является хранилище сообщений.
Чтобы отправить уведомление, поставщик хранилища сообщений или MAPI вызывает метод IMAPIAdviseSink::OnNotify зарегистрированного приемника рекомендаций. Один из параметров onNotify, структура уведомлений, содержит сведения, описывающие конкретное событие.
Примечания для исполнителей
Вы можете поддерживать уведомления с помощью MAPI или без нее. MAPI имеет три метода поддержки объектов, помогающих поставщикам служб реализовать уведомление: IMAPISupport::Subscribe, IMAPISupport::Unsubscribe и IMAPISupport::Notify. Если вы решили использовать методы поддержки MAPI, вызовите команду Subscribe при вызове метода Advise и отпустите указатель lpAdviseSink .
Если вы решили самостоятельно поддержать уведомление, вызовите метод IUnknown::AddRef приемника рекомендаций, представленного параметром lpAdviseSink , чтобы сохранить копию этого указателя. Сохраняйте эту копию до тех пор, пока метод IMsgStore::Unadvise не будет вызван для отмены регистрации.
Независимо от того, как вы поддерживаете уведомление, назначьте номер ненулевого подключения регистрации уведомления и верните его в параметре lpulConnection . Не отпускайте этот номер подключения до тех пор , пока не будет вызвана и завершена отмена отмены.
Примечания для вызывающих методов
В системах, поддерживающих несколько потоков выполнения, вызов OnNotify также может выполняться в любом потоке в любое время. Если вы должны быть уверены, что уведомления происходят только в определенное время в определенном потоке, вызовите функцию HrThisThreadAdviseSink , чтобы создать объект приемника рекомендаций, который передается в Совет.
После успешного вызова в Совет и до вызова Unadvise для отмены регистрации будьте готовы к освобождению объекта приемника рекомендаций. Вы должны освободить объект приемника рекомендаций после возврата Рекомендации , если для него не установлено определенное долгосрочное использование.
Дополнительные сведения о процессе уведомления см. в разделе Уведомление о событиях в MAPI.
Дополнительные сведения об обработке уведомлений см. в разделе Обработка уведомлений.
Справочные материалы по MFCMAPI
Пример кода MFCMAPI указан в приведенной ниже таблице.
| Файл | Функция | Comment |
|---|---|---|
| BaseDialog.cpp |
CBaseDialog::OnNotificationsOn |
MFCMAPI использует метод IMsgStore::Advise для регистрации уведомлений во всем хранилище сообщений. |