IMsgStore::Advise

项目
04/04/2023

适用于：Outlook 2013 | Outlook 2016

注册以接收影响消息存储的指定事件的通知。

HRESULT Advise(
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  ULONG ulEventMask,
  LPMAPIADVISESINK lpAdviseSink,
  ULONG_PTR lpulConnection
);

参数

cbEntryID

[in] lpEntryID 参数指向的条目标识符中的字节计数。

lpEntryID

[in]指向应生成通知的文件夹或邮件的条目标识符的指针，或 null。如果 lpEntryID 设置为 NULL， 则建议 将注册整个消息存储区上的通知。

ulEventMask

[in]一个值掩码，指示调用方感兴趣的通知事件类型，并且应包含在注册中。有一个相应的 NOTIFICATION 结构与每种类型的事件相关联，用于保存有关该事件的信息。以下是 ulEventMask 参数的有效值：

fnevCriticalError

注册有关严重错误的通知，例如内存不足。

fnevExtended

注册有关特定于特定消息存储提供程序的事件的通知。

fnevNewMail

注册有关新消息到达的通知。

fnevObjectCreated

注册有关创建新文件夹或邮件的通知。

fnevObjectCopied

注册有关正在复制的文件夹或邮件的通知。

fnevObjectDeleted

注册有关要删除的文件夹或邮件的通知。

fnevObjectModified

注册有关正在修改的文件夹或邮件的通知。

fnevObjectMoved

注册有关要移动的文件夹或邮件的通知。

fnevSearchComplete

注册有关搜索操作完成的通知。

lpAdviseSink

[in]指向建议接收器对象的指针，用于接收后续通知。此建议接收器对象必须已分配。

lpulConnection

[out]指向非零数字的指针，该数字表示调用方的建议接收器对象与会话之间的连接。

lpAdviseSink

[in]指向建议接收器对象的指针，用于接收后续通知。此建议接收器对象必须已分配。

lpulConnection

[out]指向非零连接号的指针，该编号表示调用方的建议接收器对象与消息存储之间的连接。

返回值

S_OK

注册成功。

MAPI_E_NO_SUPPORT

消息存储提供程序不支持通过消息存储注册通知。

备注

IMsgStore：：Advise 方法在调用方的建议接收器对象与消息存储或消息存储中的对象之间建立连接。当 ulEventMask 参数中指定的一个或多个事件发生到建议源对象时，此连接用于将通知发送到建议接收器。当 lpEntryID 参数指向有效的条目标识符时，建议源是由此条目标识符标识的对象。当 lpEntryID 为 NULL 时，建议源是消息存储。

若要发送通知，消息存储提供程序或 MAPI 会调用已注册的建议接收器的 IMAPIAdviseSink：：OnNotify 方法。 通知结构 OnNotify 的参数之一包含描述特定事件的信息。

针对实现者的说明

无论是否通过 MAPI 的帮助，都可以支持通知。 MAPI 有三种帮助服务提供商实现通知的支持对象方法： IMAPISupport：：Subscribe、 IMAPISupport：：Unsubscribe 和 IMAPISupport：：Notify。如果选择使用 MAPI 支持方法，请在调用 Advise 方法时调用 Subscribe 并释放 lpAdviseSink 指针。

如果选择自行支持通知，请调用 lpAdviseSink 参数表示的建议接收器的 IUnknown：：AddRef 方法，以保留此指针的副本。保留此副本，直到调用 IMsgStore：：Unadvise 方法以取消注册。

无论支持通知的方式如何，都向通知注册分配一个非零连接号，并在 lpulConnection 参数中返回它。在调用 Unadvise 并完成之前，请勿释放此连接编号。